Update documentation for bridge backup, plus tweaks

Sets default to use the backoff mechanism.

ChangeLog.txt

@@ -11,6 +11,7 @@ Broker features:
 - Add `bind_interface` option which allows a listener to be bound to a
   specific network interface, in a similar fashion to the `bind_address` option.
   Linux only.
+- Add improved bridge restart interval based on Decorrelated Jitter.
 
 Client library features:
 - Add mosquitto_subscribe_multiple() for sending subscriptions to multiple

man/mosquitto.conf.5.xml

@@ -1401,14 +1401,25 @@
 				</listitem>
 			</varlistentry>
 			<varlistentry>
-				<term><option>restart_timeout</option> <replaceable>constant | base cap</replaceable></term>
+				<term><option>restart_timeout</option> <replaceable>base cap</replaceable></term>
+				<term><option>restart_timeout</option> <replaceable>constant</replaceable></term>
 				<listitem>
 					<para>Set the amount of time a bridge using the automatic
 						start type will wait until attempting to reconnect.</para>
-					<para>It can restart on a <replaceable>constant</replaceable> period, or apply a backoff
-						mechanism using “Decorrelated Jitter”, with <replaceable>base</replaceable> and
-						<replaceable>cap</replaceable> values.</para>
-					<para>Defaults to 30 seconds.</para>
+					<para>This option can be configured to use a constant delay
+						time in seconds, or to use a backoff mechanism based on
+						"Decorrelated Jitter", which adds a degree of
+						randomness to when the restart occurs, starting at the
+						base and increasing up to the cap. Set a constant
+						timeout of 20 seconds:</para>
+						<programlisting language="config">
+restart_timeout 20</programlisting>
+					<para>Set backoff with a base (start value) of 10 seconds and a cap (upper
+						limit) of 60 seconds:</para>
+						<programlisting language="config">
+restart_timeout 10 30</programlisting>
+					<para>Defaults to jitter with a base of 5 seconds and cap
+						of 30 seconds.</para>
 				</listitem>
 			</varlistentry>
 			<varlistentry>

mosquitto.conf

@@ -838,10 +838,19 @@
 
 # Set the amount of time a bridge using the automatic start type will wait
 # until attempting to reconnect.
-# It can restart on a constant period, or apply a backoff mechanism using
-# “Decorrelated Jitter”, with base and cap values.
-# Defaults to 30 seconds.
-#restart_timeout 30
+# This option can be configured to use a constant delay time in seconds, or to
+# use a backoff mechanism based on "Decorrelated Jitter", which adds a degree
+# of randomness to when the restart occurs.
+#
+# Set a constant timeout of 20 seconds:
+# restart_timeout 20
+#
+# Set backoff with a base (start value) of 10 seconds and a cap (upper limit) of
+# 60 seconds:
+# restart_timeout 10 30
+#
+# Defaults to jitter with a base of 5 and cap of 30
+#restart_timeout 5 30
 
 # Set the amount of time a bridge using the lazy start type must be idle before
 # it will be stopped. Defaults to 60 seconds.

src/bridge.c

@@ -44,7 +44,7 @@ Contributors:
 
 #ifdef WITH_BRIDGE
 
-static void bridge_backoff_step(struct mosquitto *context);
+static void bridge__backoff_step(struct mosquitto *context);
 static void bridge__backoff_reset(struct mosquitto *context);
 
 int bridge__new(struct mosquitto_db *db, struct mosquitto__bridge *bridge)
@@ -164,7 +164,7 @@ int bridge__connect_step1(struct mosquitto_db *db, struct mosquitto *context)
 	}
 
 	/* prepare backoff for a possible failure. Restart timeout will be reset if connection gets established */
-	bridge_backoff_step(context);
+	bridge__backoff_step(context);
 
 	if(context->bridge->notifications){
 		if(context->bridge->notification_topic){
@@ -344,7 +344,7 @@ int bridge__connect(struct mosquitto_db *db, struct mosquitto *context)
 	}
 
 	/* prepare backoff for a possible failure. Restart timeout will be reset if connection gets established */
-	bridge_backoff_step(context);
+	bridge__backoff_step(context);
 
 	if(context->bridge->notifications){
 		if(context->bridge->notification_topic){
@@ -453,7 +453,7 @@ static int rand_between(int base, int cap)
 	return (rand() % (cap - base)) + base;
 }
 
-static void bridge_backoff_step(struct mosquitto *context)
+static void bridge__backoff_step(struct mosquitto *context)
 {
 	struct mosquitto__bridge *bridge;
 	if(!context || !context->bridge) return;

src/conf.c

@@ -1180,7 +1180,9 @@ int config__read_file_core(struct mosquitto__config *config, bool reload, struct
 						cur_bridge->notifications_local_only = false;
 						cur_bridge->start_type = bst_automatic;
 						cur_bridge->idle_timeout = 60;
-						cur_bridge->restart_timeout = 30;
+						cur_bridge->restart_timeout = 0;
+						cur_bridge->backoff_base = 5;
+						cur_bridge->backoff_cap = 30;
 						cur_bridge->threshold = 10;
 						cur_bridge->try_private = true;
 						cur_bridge->attempt_unsubscribe = true;
@@ -1752,7 +1754,7 @@ int config__read_file_core(struct mosquitto__config *config, bool reload, struct
 						cur_bridge->backoff_base = cur_bridge->restart_timeout;
 						cur_bridge->backoff_cap = atoi(token);
 						if(cur_bridge->backoff_cap < cur_bridge->backoff_base){
-							log__printf(NULL, MOSQ_LOG_ERR, "Error: backoff cap is lower than the base.");
+							log__printf(NULL, MOSQ_LOG_ERR, "Error: backoff cap is lower than the base in restart_timeout.");
 							return MOSQ_ERR_INVAL;
 						}
 					}