[routing-manager] introduce MultiAilDetector (openthread#11400)

This commit introduces the `MultiAilDetector` feature within the
`RoutingManager`. This feature detects whether Border Routers(BRs) on
the Thread mesh might be connected to different Adjacent
Infrastructure Links (AILs).

The feature can be enabled using the configuration option
`OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE`.

The detection mechanism operates as follows: The Routing Manager
monitors the number of peer BRs listed in the Thread Network Data and
compares this with the number of peer BRs discovered by processing
received Router Advertisements (RAs) on its local AIL.

If the count derived from Network Data consistently exceeds the count
derived from RAs for a detection period of 5 minutes, the detector
concludes that BRs are likely connected to different AILs. This
triggers a detection state change, and a registered callback is
invoked. To clear this state, a shorter window of 1 minute is used.

Public APIs and corresponding CLI commands have been added to allow
checking the current detection state and registering a callback for
state change notifications.

This commit also includes test coverage for the newly added feature.

Author: abtink

include/openthread/border_routing.h

@@ -596,6 +596,68 @@ otError otBorderRoutingGetNextPeerBrEntry(otInstance                           *
  */
 uint16_t otBorderRoutingCountPeerBrs(otInstance *aInstance, uint32_t *aMinAge);
 
+/**
+ * A callback function pointer called when the multi-AIL detection state changes.
+ *
+ * This callback function is invoked by the OpenThread stack whenever the Routing Manager determines a change in
+ * whether Border Routers on the Thread mesh might be connected to different Adjacent Infrastructure Links (AILs).
+ *
+ * See `otBorderRoutingIsMultiAilDetected()` for more details.
+ *
+ * @param[in] aDetected   `TRUE` if multiple AILs are now detected, `FALSE` otherwise.
+ * @param[in] aContext    A pointer to arbitrary context information provided when the callback was registered
+ *                        using `otBorderRoutingSetMultiAilCallback()`.
+ */
+typedef void (*otBorderRoutingMultiAilCallback)(bool aDetected, void *aContext);
+
+/**
+ * Gets the current detected state regarding multiple Adjacent Infrastructure Links (AILs).
+ *
+ * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE`.
+ *
+ * It returns whether the Routing Manager currently believes that Border Routers (BRs) on the Thread mesh may be
+ * connected to different AILs.
+ *
+ * The detection mechanism operates as follows: The Routing Manager monitors the number of peer BRs listed in the
+ * Thread Network Data (see `otBorderRoutingCountPeerBrs()`) and compares this count with the number of peer BRs
+ * discovered by processing received Router Advertisement (RA) messages on its connected AIL. If the count derived from
+ * Network Data consistently exceeds the count derived from RAs for a detection duration of 10 minutes, it concludes
+ * that BRs are likely connected to different AILs. To clear state a shorter window of 1 minute is used.
+ *
+ * The detection window of 10 minutes helps to avoid false positives due to transient changes. The Routing Manager uses
+ * 200 seconds for reachability checks of peer BRs (sending Neighbor Solicitation). Stale Network Data entries are
+ * also expected to age out within a few minutes. So a 10-minute detection time accommodates both cases.
+ *
+ * While generally effective, this detection mechanism may get less reliable in scenarios with a large number of
+ * BRs, particularly exceeding ten. This is related to the "Network Data Publisher" mechanism, where BRs might refrain
+ * from publishing their external route information in the Network Data to conserve its limited size, potentially
+ * skewing the Network Data BR count.
+ *
+ * @param[in] aInstance  A pointer to the OpenThread instance.
+ *
+ * @retval TRUE   Has detected that BRs are likely connected to multiple AILs.
+ * @retval FALSE  Has not detected (or no longer detects) that BRs are connected to multiple AILs.
+ */
+bool otBorderRoutingIsMultiAilDetected(otInstance *aInstance);
+
+/**
+ * Sets a callback function to be notified of changes in the multi-AIL detection state.
+ *
+ * Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE`.
+ *
+ * Subsequent calls to this function will overwrite the previous callback setting. Using `NULL` for @p aCallback will
+ * disable the callback.
+ *
+ * @param[in] aInstance  A pointer to the OpenThread instance.
+ * @param[in] aCallback  A pointer to the function (`otBorderRoutingMultiAilCallback`) to be called
+ *                       upon state changes, or `NULL` to unregister a previously set callback.
+ * @param[in] aContext   A pointer to application-specific context that will be passed back
+ *                       in the `aCallback` function. This can be `NULL` if no context is needed.
+ */
+void otBorderRoutingSetMultiAilCallback(otInstance                     *aInstance,
+                                        otBorderRoutingMultiAilCallback aCallback,
+                                        void                           *aContext);
+
 /**
  * Iterates over the Recursive DNS Server (RDNSS) address entries.
  *

include/openthread/instance.h

@@ -52,7 +52,7 @@ extern "C" {
  *
  * @note This number versions both OpenThread platform and user APIs.
  */
-#define OPENTHREAD_API_VERSION (498)
+#define OPENTHREAD_API_VERSION (499)
 
 /**
  * @addtogroup api-instance

src/cli/README_BR.md

@@ -33,6 +33,7 @@ Print BR command help menu.
 counters
 disable
 enable
+multiail
 omrconfig
 omrprefix
 onlinkprefix
@@ -118,6 +119,47 @@ RS TxFailed: 0
 Done
 ```
 
+### multiail
+
+Usage : `br multiail`
+
+Requires `OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE`.
+
+Get the current detected state regarding multiple Adjacent Infrastructure Links (AILs) indicating whether the Routing Manager currently believes that Border Routers (BRs) on the Thread mesh may be connected to different AILs.
+
+The detection mechanism operates as follows: The Routing Manager monitors the number of peer BRs listed in the Thread Network Data (see `br peers`) and compares this count with the number of peer BRs discovered by processing received Router Advertisement (RA) messages on its connected AIL. If the count derived from Network Data consistently exceeds the count derived from RAs for a detection duration of 10 minutes, it concludes that BRs are likely connected to different AILs. To clear the state a shorter window of 1 minute is used.
+
+The detection window of 10 minutes helps to avoid false positives due to transient changes. The Routing Manager uses 200 seconds for reachability checks of peer BRs (sending Neighbor Solicitation). Stale Network Data entries are also expected to age out within a few minutes. So a 10-minute detection time accommodates both cases.
+
+While generally effective, this detection mechanism may get less reliable in scenarios with a large number of BRs, particularly exceeding ten. This is related to the "Network Data Publisher" mechanism, where BRs might refrain from publishing their external route information in the Network Data to conserve its limited size, potentially skewing the Network Data BR count.
+
+```bash
+> br multiail
+not detected
+Done
+
+> br multiail
+detected
+Done
+```
+
+Usage: `br multiail callback enable|disable`
+
+Enable or disable callback to be notified of changes in the multi-AIL detection state.
+
+```bash
+> br multiail callback enable
+Done
+
+BR multi AIL callback: detected
+
+> br multiail
+detected
+Done
+
+BR multi AIL callback: cleared
+```
+
 ### omrconfig
 
 Usage: `br omrconfig`

src/cli/cli_br.cpp

@@ -143,6 +143,70 @@ template <> otError Br::Process<Cmd("state")>(Arg aArgs[])
     return error;
 }
 
+#if OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE
+
+template <> otError Br::Process<Cmd("multiail")>(Arg aArgs[])
+{
+    otError error = OT_ERROR_NONE;
+
+    /**
+     * @cli br multiail
+     * @code
+     * br multiail
+     * not detected
+     * @endcode
+     * @par api_copy
+     * #otBorderRoutingIsMultiAilDetected
+     */
+    if (aArgs[0].IsEmpty())
+    {
+        OutputLine("%sdetected", otBorderRoutingIsMultiAilDetected(GetInstancePtr()) ? "" : "not ");
+    }
+    /**
+     * @cli br multiail callback
+     * @code
+     * br multiail callback enable
+     * Done
+     * @endcode
+     * @cparam br multiail callback @ca{enable|disable}
+     * @par api_copy
+     * #otBorderRoutingSetMultiAilCallback
+     */
+    else if (aArgs[0] == "callback")
+    {
+        bool                            enable;
+        otBorderRoutingMultiAilCallback callback = nullptr;
+
+        SuccessOrExit(error = ParseEnableOrDisable(aArgs[1], enable));
+
+        if (enable)
+        {
+            callback = &HandleMultiAilDetected;
+        }
+
+        otBorderRoutingSetMultiAilCallback(GetInstancePtr(), callback, this);
+    }
+    else
+    {
+        error = OT_ERROR_INVALID_ARGS;
+    }
+
+exit:
+    return error;
+}
+
+void Br::HandleMultiAilDetected(bool aDetected, void *aContext)
+{
+    static_cast<Br *>(aContext)->HandleMultiAilDetected(aDetected);
+}
+
+void Br::HandleMultiAilDetected(bool aDetected)
+{
+    OutputLine("BR multi AIL callback: %s", aDetected ? "detected" : "cleared");
+}
+
+#endif // OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE
+
 otError Br::ParsePrefixTypeArgs(Arg aArgs[], PrefixType &aFlags)
 {
     otError error = OT_ERROR_NONE;
@@ -1030,6 +1094,9 @@ otError Br::Process(Arg aArgs[])
         CmdEntry("disable"),
         CmdEntry("enable"),
         CmdEntry("init"),
+#if OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE
+        CmdEntry("multiail"),
+#endif
 #if OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE
         CmdEntry("nat64prefix"),
 #endif

src/cli/cli_br.hpp

@@ -93,6 +93,11 @@ class Br : private Utils
 
     otError ParsePrefixTypeArgs(Arg aArgs[], PrefixType &aFlags);
     void    OutputRouterInfo(const otBorderRoutingRouterEntry &aEntry, RouterOutputMode aMode);
+
+#if OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE
+    static void HandleMultiAilDetected(bool aDetected, void *aContext);
+    void        HandleMultiAilDetected(bool aDetected);
+#endif
 };
 
 } // namespace Cli

src/core/api/border_routing_api.cpp

@@ -257,6 +257,22 @@ uint16_t otBorderRoutingCountPeerBrs(otInstance *aInstance, uint32_t *aMinAge)
 
 #endif
 
+#if OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE
+
+bool otBorderRoutingIsMultiAilDetected(otInstance *aInstance)
+{
+    return AsCoreType(aInstance).Get<BorderRouter::RoutingManager>().IsMultiAilDetected();
+}
+
+void otBorderRoutingSetMultiAilCallback(otInstance                     *aInstance,
+                                        otBorderRoutingMultiAilCallback aCallback,
+                                        void                           *aContext)
+{
+    AsCoreType(aInstance).Get<BorderRouter::RoutingManager>().SetMultiAilCallback(aCallback, aContext);
+}
+
+#endif
+
 #if OPENTHREAD_CONFIG_BORDER_ROUTING_DHCP6_PD_ENABLE
 
 void otBorderRoutingDhcp6PdSetEnabled(otInstance *aInstance, bool aEnabled)