8.3. Fanout Protocol

Abstract

The fanout protocol allows clients to connect to multiple brokers at once and broadcast messages to consumers connected to all of the brokers at once.

Overview

The fanout protocol enables a producer to auto-discover broker endpoints and broadcast topic messages to all of the discovered brokers. The fanout protocol gives producers a convenient mechanism for broadcasting messages to multiple brokers that are not part of a network of brokers.
The fanout protocol relies on a discovery agent to build up the list of broker URIs to which it connects.

URI syntax

Example 8.15, “Fanout URI Syntax” shows the syntax for a fanout URI.

Example 8.15. Fanout URI Syntax

fanout://(DiscoveryAgentUri)?Options
DiscoveryAgentUri is URI for the discovery agent used to build up the list of available brokers. Discovery agents are described in Section 8.1, “Discovery Agents”.
The options, ?Options, are specified in the form of a query list. The discovery options are described in Table 8.2, “Fanout Protocol Options”. You can also inject transport options as described in the section called “Setting options on the discovered transports”.
Note
If no options are required, you can drop the parentheses from the URI. The resulting URI would take the form fanout://DiscoveryAgentUri

Transport options

The fanout protocol supports the transport options described in Table 8.2, “Fanout Protocol Options”.

Table 8.2. Fanout Protocol Options

Option NameDefaultDescription
initialReconnectDelay 10Specifies, in milliseconds, how long the transport will wait before the first reconnect attempt.
maxReconnectDelay 30000Specifies, in milliseconds, the maximum amount of time to wait between reconnect attempts.
useExponentialBackOff trueSpecifies if an exponential back-off is used between reconnect attempts.
backOffMultiplier 2Specifies the exponent used in the exponential back-off algorithm.
maxReconnectAttempts 0Specifies the maximum number of reconnect attempts before an error is sent back to the client. 0 specifies unlimited attempts.
fanOutQueues falseSpecifies whether queue messages are replicated to every connected broker. For more information see the section called “Applying fanout to queue messages”.
minAckCount 2Specifies the minimum number of brokers to which the client must connect before it sends out messages. For more informaiton see the section called “Minimum number of brokers”.

Sample URI

Example 8.16, “Fanout Protocol URI” shows a discovery URI that uses a multicast discovery agent.

Example 8.16. Fanout Protocol URI

fanout://(multicast://default)?initialReconnectDelay=100

Applying fanout to queue messages

The fanout protocol replicates topic messages by sending each topic message to all of the connected brokers. By default, however, the fanout protocol does not replicate queue messages.
For queue messages, the fanout protocol picks one of the brokers at random and sends all of the queue messages to that broker. This is a sensible default, because under normal circumstances, you would not want to create more than one copy of a queue message.
It is possible to change the default behavior by setting the fanOutQueues option to true. This configures the protocol so that it also replicates queue messages.

Minimum number of brokers

By default, the fanout protocol does not start sending messages until the producer has connected to a minimum of two brokers. You can customize this minimum value using the minAckCount option.
Setting minimum number of brokers equal to the expected number of discovered brokers ensures that all of the available brokers start receiving messages at the same time. This ensures that no messages are missed if a broker starts up after the producer has started sending messages.

Using fanout with a broker network

You have to be careful when using the fanout protocol with brokers that are joined in a network of brokers.
The combination of the fanout protocol's broadcasting behavior and the nature of how messages are propagated through a network of brokers makes it likely that consumers will receive duplicate messages. If, for example, you joined four brokers into a network of brokers and connected a consumer listening for messages on topic hello.jason to broker A and connected a producer to broker B to send messages to topic hello.jason, the consumer would get one copy of the messages. If, on the other hand, the producer connects to the network using the fanout protocol, the producer will connect to every broker in the network simultaneously and start sending messages. Each of the four brokers will receive a copy of every message and deliver its copy to the consumer. So, for each message, the consumer will get four copies.