[rx-ra-tracker] use a new Events struct for callbacks (#12084)

This commit enhances `RxRaTracker` by introducing a new `Events`
struct for handling callbacks. This change replaces the previous
`HandleRxRaTrackerDecisionFactorChanged()` method with a more
versatile `HandleRxRaTrackerEvents()` that accepts the `Events`
struct as an argument.

The new `Events` struct includes boolean flags for:
- `mInitialDiscoveryFinished`
- `mDecisionFactorChanged`
- `mLocalRaHeaderChanged`

This allows `RxRaTracker` to communicate more specific events to
`RoutingManager` and `MultiAilDetector`, enabling them to take
the proper action based on the events. The `SignalTask` has been
renamed to `EventTask` to better reflect its new role in handling
these events.

src/core/border_router/multi_ail_detector.cpp

@@ -62,6 +62,15 @@ void MultiAilDetector::Stop(void)
     mReachablePeerBrCount = 0;
 }
 
+void MultiAilDetector::HandleRxRaTrackerEvents(const RxRaTracker::Events &aEvents)
+{
+    VerifyOrExit(aEvents.mDecisionFactorChanged);
+    Evaluate();
+
+exit:
+    return;
+}
+
 void MultiAilDetector::Evaluate(void)
 {
     uint16_t count;

src/core/border_router/multi_ail_detector.hpp

@@ -43,6 +43,7 @@
 #endif
 
 #include "border_router/br_types.hpp"
+#include "border_router/rx_ra_tracker.hpp"
 #include "common/callback.hpp"
 #include "common/error.hpp"
 #include "common/locator.hpp"
@@ -52,7 +53,6 @@ namespace ot {
 namespace BorderRouter {
 
 class NetDataBrTracker;
-class RxRaTracker;
 class RoutingManager;
 
 /**
@@ -110,7 +110,7 @@ private:
     void HandleTimer(void);
 
     // Callback from `RxRaTracker`
-    void HandleRxRaTrackerDecisionFactorChanged(void) { Evaluate(); }
+    void HandleRxRaTrackerEvents(const RxRaTracker::Events &aEvents);
 
     using DetectCallback = Callback<MultiAilCallback>;
     using DetectTimer    = TimerMilliIn<MultiAilDetector, &MultiAilDetector::HandleTimer>;

src/core/border_router/routing_manager.cpp

@@ -599,19 +599,30 @@ exit:
     return;
 }
 
-void RoutingManager::HandleRxRaTrackerDecisionFactorChanged(void)
+void RoutingManager::HandleRxRaTrackerEvents(const RxRaTracker::Events &aEvents)
 {
-    // This is a callback from `RxRaTracker` indicating that
-    // there has been a change impacting one of the decision
-    // factors.
+    // This is the callback from `RxRaTracker`.
 
     VerifyOrExit(mIsRunning);
 
-    mOnLinkPrefixManager.HandleRxRaTrackerChanged();
+    if (aEvents.mDecisionFactorChanged)
+    {
+        mOnLinkPrefixManager.HandleRxRaTrackerChanged();
 #if OPENTHREAD_CONFIG_NAT64_BORDER_ROUTING_ENABLE
-    mNat64PrefixManager.HandleRaDiscoverChanged();
+        mNat64PrefixManager.HandleRxRaTrackerChanged();
 #endif
-    mRoutePublisher.Evaluate();
+        mRoutePublisher.Evaluate();
+    }
+
+    if (aEvents.mLocalRaHeaderChanged)
+    {
+        ScheduleRoutingPolicyEvaluation(kAfterRandomDelay);
+    }
+
+    if (aEvents.mInitialDiscoveryFinished)
+    {
+        ScheduleRoutingPolicyEvaluation(kImmediately);
+    }
 
 exit:
     return;
@@ -2422,7 +2433,7 @@ void RoutingManager::Nat64PrefixManager::HandleInfraIfDiscoverDone(const Ip6::Pr
     Get<RoutingManager>().ScheduleRoutingPolicyEvaluation(kAfterRandomDelay);
 }
 
-void RoutingManager::Nat64PrefixManager::HandleRaDiscoverChanged(void)
+void RoutingManager::Nat64PrefixManager::HandleRxRaTrackerChanged(void)
 {
     const Ip6::Prefix &favoredPrefix = Get<RxRaTracker>().GetFavoredNat64Prefix();
 

src/core/border_router/routing_manager.hpp

@@ -827,7 +827,7 @@ private:
         const Ip6::Prefix &GetFavoredPrefix(RoutePreference &aPreference) const;
         void               Evaluate(void);
         void               HandleInfraIfDiscoverDone(const Ip6::Prefix &aPrefix);
-        void               HandleRaDiscoverChanged(void);
+        void               HandleRxRaTrackerChanged(void);
         void               HandleTimer(void);
 
     private:
@@ -1028,9 +1028,11 @@ private:
 
     bool NetworkDataContainsUlaRoute(void) const;
 
-    void HandleRxRaTrackerDecisionFactorChanged(void);
     void HandleLocalOnLinkPrefixChanged(void);
 
+    // Callback from `RxRaTracker`
+    void HandleRxRaTrackerEvents(const RxRaTracker::Events &aEvents);
+
     static bool IsValidBrUlaPrefix(const Ip6::Prefix &aBrUlaPrefix);
 
     //------------------------------------------------------------------------------------------------------------------

src/core/border_router/rx_ra_tracker.cpp

@@ -57,10 +57,11 @@ RxRaTracker::RxRaTracker(Instance &aInstance)
     , mStaleTimer(aInstance)
     , mRouterTimer(aInstance)
     , mRdnssAddrTimer(aInstance)
-    , mSignalTask(aInstance)
+    , mEventTask(aInstance)
     , mRdnssAddrTask(aInstance)
 {
     mLocalRaHeader.Clear();
+    mPendingEvents.Clear();
 }
 
 void RxRaTracker::SetEnabled(bool aEnable, Requester aRequester)
@@ -68,14 +69,33 @@ void RxRaTracker::SetEnabled(bool aEnable, Requester aRequester)
     switch (aRequester)
     {
     case kRequesterRoutingManager:
+        VerifyOrExit(mRoutingManagerEnabled != aEnable);
         mRoutingManagerEnabled = aEnable;
         break;
     case kRequesterMultiAilDetector:
+        VerifyOrExit(mMultiAilDetectorEnabled != aEnable);
         mMultiAilDetectorEnabled = aEnable;
         break;
     }
 
     UpdateState();
+
+    // If `RoutingManager` enables `RxRaTracker`, we check if it was
+    // already enabled and had previously completed its initial
+    // router discovery (sending RS messages). If so, we re-signal
+    // the 'initial discovery finished' and 'decision factors
+    // changed' events. This ensures `RoutingManager` properly
+    // evaluates its state and takes the next actions.
+
+    VerifyOrExit((aRequester == kRequesterRoutingManager) && mRoutingManagerEnabled);
+    VerifyOrExit(mIsRunning && mInitialDiscoveryFinished);
+
+    mPendingEvents.mInitialDiscoveryFinished = true;
+    mPendingEvents.mDecisionFactorChanged    = true;
+    mEventTask.Post();
+
+exit:
+    return;
 }
 
 void RxRaTracker::UpdateState(void)
@@ -138,8 +158,13 @@ void RxRaTracker::HandleRsSenderFinished(TimeMilli aStartTime)
 
     RemoveOrDeprecateOldEntries(aStartTime);
 
-    mInitialDiscoveryFinished = true;
-    Get<RoutingManager>().ScheduleRoutingPolicyEvaluation(RoutingManager::kImmediately);
+    if (!mInitialDiscoveryFinished)
+    {
+        mInitialDiscoveryFinished = true;
+
+        mPendingEvents.mInitialDiscoveryFinished = true;
+        mEventTask.Post();
+    }
 }
 
 void RxRaTracker::HandleRouterAdvertisement(const InfraIf::Icmp6Packet &aPacket, const Ip6::Address &aSrcAddress)
@@ -279,7 +304,8 @@ void RxRaTracker::ProcessRaHeader(const RouterAdvert::Header &aRaHeader, Router
 
         if (mLocalRaHeader != oldHeader)
         {
-            Get<RoutingManager>().ScheduleRoutingPolicyEvaluation(RoutingManager::kAfterRandomDelay);
+            mPendingEvents.mLocalRaHeaderChanged = true;
+            mEventTask.Post();
         }
     }
 
@@ -647,7 +673,7 @@ exit:
     return;
 }
 
-void RxRaTracker::HandleNotifierEvents(Events aEvents)
+void RxRaTracker::HandleNotifierEvents(ot::Events aEvents)
 {
     if (aEvents.Contains(kEventThreadNetdataChanged))
     {
@@ -826,7 +852,8 @@ void RxRaTracker::Evaluate(void)
 
     if (oldFactors != mDecisionFactors)
     {
-        mSignalTask.Post();
+        mPendingEvents.mDecisionFactorChanged = true;
+        mEventTask.Post();
     }
 
     //- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
@@ -984,13 +1011,23 @@ exit:
 
 void RxRaTracker::HandleExpirationTimer(void) { Evaluate(); }
 
-void RxRaTracker::HandleSignalTask(void)
+void RxRaTracker::HandleEventTask(void)
 {
+    Events events;
+
+    VerifyOrExit(mInitialDiscoveryFinished);
+
+    events = mPendingEvents;
+    mPendingEvents.Clear();
+
+    Get<RoutingManager>().HandleRxRaTrackerEvents(events);
+
 #if OPENTHREAD_CONFIG_BORDER_ROUTING_MULTI_AIL_DETECTION_ENABLE
-    Get<MultiAilDetector>().HandleRxRaTrackerDecisionFactorChanged();
+    Get<MultiAilDetector>().HandleRxRaTrackerEvents(events);
 #endif
 
-    Get<RoutingManager>().HandleRxRaTrackerDecisionFactorChanged();
+exit:
+    return;
 }
 
 void RxRaTracker::HandleRdnssAddrTask(void) { mRdnssCallback.InvokeIfSet(); }

src/core/border_router/rx_ra_tracker.hpp

@@ -43,6 +43,7 @@
 #include "border_router/br_types.hpp"
 #include "border_router/infra_if.hpp"
 #include "common/callback.hpp"
+#include "common/clearable.hpp"
 #include "common/equatable.hpp"
 #include "common/error.hpp"
 #include "common/heap_allocatable.hpp"
@@ -86,6 +87,18 @@ public:
         kRequesterMultiAilDetector, ///< Requested by `MultiAilDetector`.
     };
 
+    /**
+     * Represents different events that can occur within the `RxRaTracker`.
+     *
+     * Used in callbacks `HandleRxRaTrackerEvents()` to notify other BR components of changes/events by `RxRaTracker`.
+     */
+    struct Events : public Clearable<Events>
+    {
+        bool mInitialDiscoveryFinished : 1; ///< Indicates that the initial router discovery process is finished.
+        bool mDecisionFactorChanged : 1;    ///< Indicates that a decision factor (e.g., on-link prefix) was changed.
+        bool mLocalRaHeaderChanged : 1;     ///< Indicates that the tracked local RA header was changed.
+    };
+
     /**
      * Initializes the `RxRaTracker` object.
      *
@@ -588,7 +601,7 @@ private:
 #if OPENTHREAD_CONFIG_HISTORY_TRACKER_ENABLE
     void ReportChangesToHistoryTracker(Router &aRouter, bool aRemoved);
 #endif
-    void HandleNotifierEvents(Events aEvents);
+    void HandleNotifierEvents(ot::Events aEvents);
     void HandleNetDataChange(void);
 
     // Callbacks from `InfraIf`
@@ -597,7 +610,7 @@ private:
     void HandleNeighborAdvertisement(const InfraIf::Icmp6Packet &aPacket);
 
     // Tasklet or timer callbacks
-    void HandleSignalTask(void);
+    void HandleEventTask(void);
     void HandleRdnssAddrTask(void);
     void HandleExpirationTimer(void);
     void HandleStaleTimer(void);
@@ -612,7 +625,7 @@ private:
 
     static const char *RouterAdvOriginToString(RouterAdvOrigin aRaOrigin);
 
-    using SignalTask      = TaskletIn<RxRaTracker, &RxRaTracker::HandleSignalTask>;
+    using EventTask       = TaskletIn<RxRaTracker, &RxRaTracker::HandleEventTask>;
     using RdnssAddrTask   = TaskletIn<RxRaTracker, &RxRaTracker::HandleRdnssAddrTask>;
     using ExpirationTimer = TimerMilliIn<RxRaTracker, &RxRaTracker::HandleExpirationTimer>;
     using StaleTimer      = TimerMilliIn<RxRaTracker, &RxRaTracker::HandleStaleTimer>;
@@ -626,6 +639,7 @@ private:
     bool                 mMultiAilDetectorEnabled : 1;
     bool                 mIsRunning : 1;
     bool                 mInitialDiscoveryFinished : 1;
+    Events               mPendingEvents;
     RsSender             mRsSender;
     DecisionFactors      mDecisionFactors;
     RouterList           mRouters;
@@ -634,7 +648,7 @@ private:
     StaleTimer           mStaleTimer;
     RouterTimer          mRouterTimer;
     RdnssAddrTimer       mRdnssAddrTimer;
-    SignalTask           mSignalTask;
+    EventTask            mEventTask;
     RdnssAddrTask        mRdnssAddrTask;
     RdnssCallback        mRdnssCallback;
     RouterAdvert::Header mLocalRaHeader;