Merge remote-tracking branch 'origin/upgrade-docu' into main-controller-in-docker

Author: FerTV

nebula/addons/attacks/communications/communicationattack.py

@@ -44,6 +44,28 @@ def decorator(self, *args):
         pass
 
     async def select_targets(self):
+        """
+        Selects a subset of neighboring nodes as attack targets based on the configured selectivity percentage.
+
+        This method determines which neighboring nodes should be targeted in the current round of attack.
+        If the selectivity percentage is less than 100%, it samples a subset of the currently connected direct neighbors.
+        The selection behavior can be influenced by a `selection_interval`:
+            - If `selection_interval` is set, target selection occurs only at rounds that are multiples of this interval.
+            - If no interval is defined but no targets have been selected yet, targets are selected once.
+        If the selectivity is 100%, all direct neighbors are selected as targets.
+
+        Target addresses are retrieved from the CommunicationsManager (only direct connections).
+        The number of selected targets is at least 1.
+
+        Logs are emitted at each selection event to indicate which targets were chosen.
+
+        Increments the internal `last_selection_round` counter after execution.
+
+        Notes:
+            - The `self.targets` attribute is updated in-place.
+            - The `self.last_selection_round` attribute tracks when the selection was last performed.
+
+    """
         if self.selectivity_percentage != 100:
             if self.selection_interval:
                 if self.last_selection_round % self.selection_interval == 0:
@@ -63,8 +85,6 @@ async def select_targets(self):
         logging.info(f"Selected {self.selectivity_percentage}% targets from neighbors: {self.targets}")
         self.last_selection_round += 1
 
-        self.last_selection_round += 1
-
     async def _inject_malicious_behaviour(self):
         """Inject malicious behavior into the target method."""
         decorated_method = self.decorator(self.decorator_args)(self.original_method)

nebula/addons/gps/gpsmodule.py

@@ -2,20 +2,63 @@
 
 
 class GPSModule(ABC):
+    """
+    Abstract base class representing a GPS module interface.
+
+    This class defines the required asynchronous methods that any concrete GPS module implementation must provide.
+    These methods allow for lifecycle control (start/stop), status checking, and distance calculation between coordinates.
+
+    Any subclass must implement all the following asynchronous methods:
+    - `start()`: Begins GPS tracking or data acquisition.
+    - `stop()`: Halts the GPS module's operation.
+    - `is_running()`: Checks whether the GPS module is currently active.
+    - `calculate_distance()`: Computes the distance between two geographic coordinates (latitude and longitude).
+
+    All implementations should ensure that methods are non-blocking and integrate smoothly with async event loops.
+    """
+
     @abstractmethod
     async def start(self):
+        """
+        Starts the GPS module operation.
+
+        This may involve initiating hardware tracking, establishing connections, or beginning periodic updates.
+        """
         pass
 
     @abstractmethod
     async def stop(self):
+        """
+        Stops the GPS module operation.
+
+        Ensures that any background tasks or hardware interactions are properly terminated.
+        """
         pass
 
     @abstractmethod
     async def is_running(self):
+        """
+        Checks whether the GPS module is currently active.
+
+        Returns:
+            bool: True if the module is running, False otherwise.
+        """
         pass
 
     @abstractmethod
     async def calculate_distance(self, self_lat, self_long, other_lat, other_long):
+        """
+        Calculates the distance between two geographic points.
+
+        Args:
+            self_lat (float): Latitude of the source point.
+            self_long (float): Longitude of the source point.
+            other_lat (float): Latitude of the target point.
+            other_long (float): Longitude of the target point.
+
+        Returns:
+            float: Distance in meters (or implementation-defined units) between the two coordinates.
+        """
         pass
 
 

nebula/addons/mobility.py

@@ -203,17 +203,17 @@ async def change_geo_location_nearest_neighbor_strategy(
         if self._verbose:
             logging.info("📍  Changing geo location towards the nearest neighbor")
         scale_factor = min(1, self.max_movement_nearest_strategy / distance)
-        # Calcular el ángulo hacia el vecino
+        # Calculating angle to the neighbor
         angle = math.atan2(neighbor_longitude - longitude, neighbor_latitude - latitude)
-        # Conversión de movimiento máximo a grados
-        max_lat_change = self.max_movement_nearest_strategy / 111000  # Cambio en grados para latitud
+        # Convert maximum movement to angle
+        max_lat_change = self.max_movement_nearest_strategy / 111000  # Change degree to latitude
         max_lon_change = self.max_movement_nearest_strategy / (
             111000 * math.cos(math.radians(latitude))
-        )  # Cambio en grados para longitud
-        # Aplicar escala y dirección
+        )  # Change dregree for longitude
+        # Scale and direction
         delta_lat = max_lat_change * math.cos(angle) * scale_factor
         delta_lon = max_lon_change * math.sin(angle) * scale_factor
-        # Actualizar latitud y longitud
+        # Update values
         new_latitude = latitude + delta_lat
         new_longitude = longitude + delta_lon
         await self.set_geo_location(new_latitude, new_longitude)

nebula/addons/networksimulation/networksimulator.py

@@ -2,24 +2,73 @@
 
 
 class NetworkSimulator(ABC):
+    """
+    Abstract base class representing a network simulator interface.
+
+    This interface defines the required methods for controlling and simulating network conditions between nodes.
+    A concrete implementation is expected to manage artificial delays, bandwidth restrictions, packet loss, 
+    or other configurable conditions typically used in network emulation or testing.
+
+    Required asynchronous methods:
+    - `start()`: Initializes the network simulation module.
+    - `stop()`: Shuts down the simulation and cleans up any active conditions.
+    - `set_thresholds(thresholds)`: Configures system-wide thresholds (e.g., max/min delay or distance mappings).
+    - `set_network_conditions(dest_addr, distance)`: Applies network constraints to a target address based on distance.
+
+    Synchronous method:
+    - `clear_network_conditions(interface)`: Clears any simulated network configuration for a given interface.
+
+    All asynchronous methods should be non-blocking to support integration in async systems.
+    """
+
     @abstractmethod
     async def start(self):
+        """
+        Starts the network simulation module.
+
+        This might involve preparing network interfaces, initializing tools like `tc`, or configuring internal state.
+        """
         pass
 
     @abstractmethod
     async def stop(self):
+        """
+        Stops the network simulation module.
+
+        Cleans up any modifications made to network interfaces or system configuration.
+        """
         pass
 
     @abstractmethod
     async def set_thresholds(self, thresholds: dict):
+        """
+        Sets threshold values for simulating conditions.
+
+        Args:
+            thresholds (dict): A dictionary specifying condition thresholds,
+                               e.g., {'low': 100, 'medium': 200, 'high': 300}, or distance-delay mappings.
+        """
         pass
 
     @abstractmethod
     async def set_network_conditions(self, dest_addr, distance):
+        """
+        Applies network simulation settings to a given destination based on the computed distance.
+
+        Args:
+            dest_addr (str): The address of the destination node (e.g., IP or identifier).
+            distance (float): The physical or logical distance used to determine the simulation severity.
+        """
         pass
 
     @abstractmethod
     def clear_network_conditions(self, interface):
+        """
+        Clears any simulated network conditions applied to the specified network interface.
+
+        Args:
+            interface (str): The name of the network interface to restore (e.g., 'eth0').
+        """
         pass
 
 

nebula/core/addonmanager.py

@@ -10,12 +10,44 @@
 
 
 class AddondManager:
+    """
+    Responsible for initializing and managing system add-ons.
+
+    This class handles the lifecycle of optional services (add-ons) such as mobility simulation,
+    GPS module, and network simulation. Add-ons are conditionally deployed based on the provided configuration.
+    """
+    
     def __init__(self, engine: "Engine", config: Config):
+        """
+        Initializes the AddondManager instance.
+
+        Args:
+            engine (Engine): Reference to the main engine instance of the system.
+            config (dict): Configuration object containing participant settings for enabling add-ons.
+
+        This constructor sets up the internal references to the engine and configuration, and
+        initializes the list of add-ons to be managed.
+        """
         self._engine = engine
         self._config = config
         self._addons = []
 
     async def deploy_additional_services(self):
+        """
+        Deploys and starts additional services based on the participant's configuration.
+
+        This method checks the configuration to determine which optional components should be
+        activated. It supports:
+            - Mobility simulation (e.g., moving node behavior).
+            - GPS module (e.g., geolocation updates).
+            - Network simulation (e.g., changing connectivity conditions).
+
+        All enabled add-ons are instantiated and started asynchronously.
+
+        Notes:
+            - Add-ons are stored in the internal list `_addons` for lifecycle management.
+            - Services are only launched if the corresponding configuration flags are set.
+        """
         print_msg_box(msg="Deploying Additional Services", indent=2, title="Addons Manager")
         if self._config.participant["trustworthiness"]:
             from nebula.addons.trustworthiness.trustworthiness import Trustworthiness

nebula/core/aggregation/aggregator.py

@@ -15,27 +15,6 @@
 class AggregatorException(Exception):
     pass
 
-
-def create_target_aggregator(config, engine):
-    from nebula.core.aggregation.fedavg import FedAvg
-    from nebula.core.aggregation.krum import Krum
-    from nebula.core.aggregation.median import Median
-    from nebula.core.aggregation.trimmedmean import TrimmedMean
-
-    ALGORITHM_MAP = {
-        "FedAvg": FedAvg,
-        "Krum": Krum,
-        "Median": Median,
-        "TrimmedMean": TrimmedMean,
-    }
-    algorithm = config.participant["defense_args"]["target_aggregation"]
-    aggregator = ALGORITHM_MAP.get(algorithm)
-    if aggregator:
-        return aggregator(config=config, engine=engine)
-    else:
-        raise AggregatorException(f"Aggregation algorithm {algorithm} not found.")
-
-
 class Aggregator(ABC):
     def __init__(self, config=None, engine=None):
         self.config = config
@@ -59,6 +38,7 @@ def __repr__(self):
 
     @property
     def us(self):
+        """Federation type UpdateHandler (e.g. DFL-UpdateHandler, CFL-UpdateHandler...)"""
         return self._update_storage
 
     @abstractmethod
@@ -71,6 +51,20 @@ async def init(self):
         await self.us.init(self.config)
 
     async def update_federation_nodes(self, federation_nodes: set):
+        """
+        Updates the current set of nodes expected to participate in the upcoming aggregation round.
+
+        This method informs the update handler (`us`) about the new set of federation nodes, 
+        clears any pending models, and attempts to acquire the aggregation lock to prepare 
+        for model aggregation. If the aggregation process is already running, it raises an exception.
+
+        Args:
+            federation_nodes (set): A set of addresses representing the nodes expected to contribute 
+                                    updates for the next aggregation round.
+
+        Raises:
+            Exception: If the aggregation process is already running and the lock is currently held.
+        """
         await self.us.round_expected_updates(federation_nodes=federation_nodes)
 
         if not self._aggregation_done_lock.locked():
@@ -86,6 +80,23 @@ def get_nodes_pending_models_to_aggregate(self):
         return self._federation_nodes
 
     async def get_aggregation(self):
+        """
+        Handles the aggregation process for a training round.
+
+        This method waits for all expected model updates from federation nodes or until a timeout occurs.
+        It uses an asynchronous lock to coordinate access and includes an early exit mechanism if all
+        updates are received before the timeout. Once the condition is satisfied, it releases the lock,
+        collects the updates, identifies any missing nodes, and publishes an `AggregationEvent`.
+        Finally, it runs the aggregation algorithm and returns the result.
+
+        Returns:
+            Any: The result of the aggregation process, as returned by `run_aggregation`.
+
+        Raises:
+            TimeoutError: If the aggregation lock is not acquired within the defined timeout.
+            asyncio.CancelledError: If the aggregation lock acquisition is cancelled.
+            Exception: For any other unexpected errors during the aggregation process.
+        """
         try:
             timeout = self.config.participant["aggregator_args"]["aggregation_timeout"]
             logging.info(f"Aggregation timeout: {timeout} starts...")