# Shared Subscriptions

The Protocol Mapper supports MQTT 5 shared subscriptions, which enables load balancing across multiple clients and horizontal scaling. When multiple clients subscribe to a topic as a shared group, the broker distributes each message to only one client within that group. You can also use [Rule Engine](https://docs.cybus.io/2-0-6/documentation/services/rule-engine) context variables with shared subscriptions for advanced use cases.

{% hint style="info" %}
While shared subscriptions are a feature of MQTT5, you can also use them with MQTT 3.1.1.
{% endhint %}

{% hint style="info" %}
For more information, consult both this documentation and the official MQTT specification section on shared subscriptions in the OASIS standard: <https://docs.oasis-open.org/mqtt/mqtt/v5.0/os/mqtt-v5.0-os.html#_Toc3901250>
{% endhint %}

## Use Cases for Shared Subscriptions

Shared subscriptions enable multiple clients to efficiently share and process MQTT messages, providing key benefits for scalable and reliable systems.

Here are some key use cases for shared subscriptions:

* **Load balancing:** Shared Subscriptions enable multiple clients to share the message load for a single topic. Instead of each client receiving all messages, the broker distributes each message to one client in the group, ensuring an even distribution of messages.
* **Scalability:** Shared Subscriptions improve system scalability by allowing additional clients to be added to the group as needed. This ensures that higher message volumes can be handled without overwhelming individual clients.
* **Fault tolerance:** If a client in a shared subscription group becomes unavailable, other clients in the group continue to receive messages, increasing the overall reliability of the system.
* **Optimized resource usage:** By delivering each message to only one client within the group, Shared Subscriptions reduce bandwidth and resource consumption.
* **Simplified client management:** The MQTT broker handles load balancing and message distribution, eliminating the need for complex client-side logic to manage message loads or failover mechanisms.

## Example of a Shared Subscriptions Workflow

The diagram below shows how messages are routed when **MQTT Client 5** publishes to the `input` topic to the broker.

* **MQTT Client 1** and **MQTT Client 2** are grouped together in **Group 1**. Each message is forwarded to only one group member. In this example, **MQTT Client 1** receives messages 1 and 3, while **MQTT Client 2** receives messages 2 and 4.
* **MQTT Client 3** is the only member of **Group 2**, meaning it receives all messages published to the topic.
* **MQTT Client 4** is subscribed directly to the `input` topic without using the shared subscription feature, so it receives every message, regardless of the group distribution.

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-71277b9a7e3ba1c81a3422907a3c9e9b2122ae3e%2Fshared-subscriptions-workflow.jpg?alt=media" alt=""><figcaption></figcaption></figure>

## Behavior of Protocol Mapper Agents

For Protocol Mapper agents, all mappings from a single agent default to using the same **MQTT Connection**.

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-daf230a882c79c41ebdd3acb97e8de5107246632%2Fshared-subscriptions-protocol-mapper-agents-1.jpg?alt=media" alt=""><figcaption></figcaption></figure>

From the broker’s perspective, the **MQTT Connection** is a single client subscribing to all topics and dispatching messages to the relevant mappings.

<figure><img src="https://639096190-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FfDpOJO2upcq5EpoSahvK%2Fuploads%2Fgit-blob-3baf755b83f3993b619465a2c3aab7fc7b57dff8%2Fshared-subscriptions-protocol-mapper-agents-2.jpg?alt=media" alt=""><figcaption></figcaption></figure>

For shared subscriptions, **MQTT Connections** are also treated as single clients. The broker dispatches messages according to the shared subscription group.

**Example**

If four messages are published on the input topic, client1 receives messages 1 and 3, and client2 receives messages 2 and 4. However, mappings such as mapping1 and mapping2 in the same group will both receive the same messages (1 and 3), even though they share the same subscription group.