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”.
| Option Name | Default | Description |
|---|---|---|
initialReconnectDelay | 10 | Specifies, in milliseconds, how long the transport will wait before the first reconnect attempt. |
maxReconnectDelay | 30000 | Specifies, in milliseconds, the maximum amount of time to wait between reconnect attempts. |
useExponentialBackOff | true | Specifies if an exponential back-off is used between reconnect attempts. |
backOffMultiplier | 2 | Specifies the exponent used in the exponential back-off algorithm. |
maxReconnectAttempts | -1 | Specifies the maximum number of reconnect attempts before an error is sent back to the client. -1 specifies unlimited attempts. 0 denotes that reconnects are disabled, i.e., try once to reconnect. Values greater than 0 denote the maximum number of reconnect attempts. |
fanOutQueues | false | Specifies whether queue messages are replicated to every connected broker. For more information see the section called “Applying fanout to queue messages”. |
minAckCount | 2 | Specifies 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.
