Add documentation for minimum wildcard subscription depth

man/flashmq.conf.5

@@ -5,7 +5,7 @@
 \\$2 \(la\\$1\(ra\\$3
 ..
 .if \n(.g .mso www.tmac
-.TH flashmq.conf 5 "31 December 2023" "" ""
+.TH flashmq.conf 5 "5 February 2024" "" ""
 .SH NAME
 flashmq.conf \- FlashMQ configuration file format
 .SH SYNOPSIS
@@ -217,6 +217,18 @@ When having multiple subscribers on a shared subscription (like '$share/myshare/
 
 Default: \fIround_robin\fR
 .TP 
+\*(T<\fBminimum_wildcard_subscription_depth\fR\*(T> \fInumber\fR 
+Defines the minimum level of the first wildcard topic filter (\*(T<\fB#\fR\*(T> and \*(T<\fB+\fR\*(T>). In a topic filter like \*(T<\fBsensors/temperature/#\fR\*(T>, that is 2. If you specify 2, a subscription to \*(T<\fBsensors/#\fR\*(T> will be denied. Remember that only MQTT 3.1.1 and newer actually notify the client of the denial in the sub-ack packet.
+
+The reason you may want to limit it, is performance. If you have a base message load of 100,000 messages per second, each client subscribing to \*(T<\fB#\fR\*(T> causes that many permission checks per second. If you have 100 clients doing that, there will be 10 million permission checks per second.
+
+Default: \fI0\fR
+.TP 
+\*(T<\fBwildcard_subscription_deny_mode\fR\*(T> \fIdeny_all/deny_retained_only\fR 
+For \*(T<\fBminimum_wildcard_subscription_depth\fR\*(T>, specify what you want to deny. Trying to give a client all retained messages can cause quite some load, so only denying the retained messages upon receiving a broad wildcard subscription can be useful if you have a low enough general message volume, but a high number of retained messages. 
+
+Default: \*(T<deny_all\*(T>
+.TP 
 \*(T<\fBinclude_dir\fR\*(T> \fI/path/to/dir\fR 
 Load *.conf files from the specified directory, to merge with the main configuration file.
 

man/flashmq.conf.5.dbk5

@@ -445,6 +445,33 @@
         </listitem>
       </varlistentry>
 
+      <varlistentry xml:id="minimum_wildcard_subscription_depth">
+        <term><option>minimum_wildcard_subscription_depth</option> <replaceable>number</replaceable></term>
+        <listitem>
+          <para>
+            Defines the minimum level of the first wildcard topic filter (<option>#</option> and <option>+</option>). In a topic filter like <option>sensors/temperature/#</option>, that is 2. If you specify 2, a subscription to <option>sensors/#</option> will be denied. Remember that only MQTT 3.1.1 and newer actually notify the client of the denial in the sub-ack packet.
+          </para>
+          <para>
+            The reason you may want to limit it, is performance. If you have a base message load of 100,000 messages per second, each client subscribing to <option>#</option> causes that many permission checks per second. If you have 100 clients doing that, there will be 10 million permission checks per second.
+          </para>
+          <para>
+            Default: <replaceable>0</replaceable>
+          </para>
+        </listitem>
+      </varlistentry>
+
+      <varlistentry xml:id="wildcard_subscription_deny_mode">
+        <term><option>wildcard_subscription_deny_mode</option> <replaceable>deny_all/deny_retained_only</replaceable></term>
+        <listitem>
+          <para>
+            For <option>minimum_wildcard_subscription_depth</option>, specify what you want to deny. Trying to give a client all retained messages can cause quite some load, so only denying the retained messages upon receiving a broad wildcard subscription can be useful if you have a low enough general message volume, but a high number of retained messages. 
+          </para>
+          <para>
+            Default: <literal>deny_all</literal>
+          </para>
+        </listitem>
+      </varlistentry>
+
       <varlistentry xml:id="include_dir">
         <term><option>include_dir</option> <replaceable>/path/to/dir</replaceable></term>
         <listitem>

man/flashmq.conf.5.html

@@ -501,6 +501,33 @@
 
 
 
+        <dt id="minimum_wildcard_subscription_depth"><code class="option">minimum_wildcard_subscription_depth</code> <code class="replaceable">number</code><a class="hash-anchor" href="#minimum_wildcard_subscription_depth">#</a></dt>
+        <dd>
+          <p>
+            Defines the minimum level of the first wildcard topic filter (<code class="option">#</code> and <code class="option">+</code>). In a topic filter like <code class="option">sensors/temperature/#</code>, that is 2. If you specify 2, a subscription to <code class="option">sensors/#</code> will be denied. Remember that only MQTT 3.1.1 and newer actually notify the client of the denial in the sub-ack packet.
+          </p>
+          <p>
+            The reason you may want to limit it, is performance. If you have a base message load of 100,000 messages per second, each client subscribing to <code class="option">#</code> causes that many permission checks per second. If you have 100 clients doing that, there will be 10 million permission checks per second.
+          </p>
+          <p>
+            Default: <code class="replaceable">0</code>
+          </p>
+        </dd>
+
+
+
+        <dt id="wildcard_subscription_deny_mode"><code class="option">wildcard_subscription_deny_mode</code> <code class="replaceable">deny_all/deny_retained_only</code><a class="hash-anchor" href="#wildcard_subscription_deny_mode">#</a></dt>
+        <dd>
+          <p>
+            For <code class="option">minimum_wildcard_subscription_depth</code>, specify what you want to deny. Trying to give a client all retained messages can cause quite some load, so only denying the retained messages upon receiving a broad wildcard subscription can be useful if you have a low enough general message volume, but a high number of retained messages. 
+          </p>
+          <p>
+            Default: <code class="literal">deny_all</code>
+          </p>
+        </dd>
+
+
+
         <dt id="include_dir"><code class="option">include_dir</code> <code class="replaceable">/path/to/dir</code><a class="hash-anchor" href="#include_dir">#</a></dt>
         <dd>
           <p>