flwr 1.19.0__py3-none-any.whl → 1.21.0__py3-none-any.whl

flwr/server/superlink/simulation/simulationio_servicer.py

@@ -34,6 +34,16 @@ from flwr.common.serde import (
 )
 from flwr.common.typing import Fab, RunStatus
 from flwr.proto import simulationio_pb2_grpc
+from flwr.proto.appio_pb2 import (  # pylint: disable=E0611
+    ListAppsToLaunchRequest,
+    ListAppsToLaunchResponse,
+    PullAppInputsRequest,
+    PullAppInputsResponse,
+    PushAppOutputsRequest,
+    PushAppOutputsResponse,
+    RequestTokenRequest,
+    RequestTokenResponse,
+)
 from flwr.proto.heartbeat_pb2 import (  # pylint: disable=E0611
     SendAppHeartbeatRequest,
     SendAppHeartbeatResponse,
@@ -45,20 +55,16 @@ from flwr.proto.log_pb2 import (  # pylint: disable=E0611
 from flwr.proto.run_pb2 import (  # pylint: disable=E0611
     GetFederationOptionsRequest,
     GetFederationOptionsResponse,
+    GetRunRequest,
+    GetRunResponse,
     GetRunStatusRequest,
     GetRunStatusResponse,
     UpdateRunStatusRequest,
     UpdateRunStatusResponse,
 )
-from flwr.proto.simulationio_pb2 import (  # pylint: disable=E0611
-    PullSimulationInputsRequest,
-    PullSimulationInputsResponse,
-    PushSimulationOutputsRequest,
-    PushSimulationOutputsResponse,
-)
-from flwr.server.superlink.ffs.ffs_factory import FfsFactory
 from flwr.server.superlink.linkstate import LinkStateFactory
 from flwr.server.superlink.utils import abort_if
+from flwr.supercore.ffs import FfsFactory
 
 
 class SimulationIoServicer(simulationio_pb2_grpc.SimulationIoServicer):
@@ -71,23 +77,73 @@ class SimulationIoServicer(simulationio_pb2_grpc.SimulationIoServicer):
         self.ffs_factory = ffs_factory
         self.lock = threading.RLock()
 
-    def PullSimulationInputs(
-        self, request: PullSimulationInputsRequest, context: ServicerContext
-    ) -> PullSimulationInputsResponse:
+    def ListAppsToLaunch(
+        self,
+        request: ListAppsToLaunchRequest,
+        context: grpc.ServicerContext,
+    ) -> ListAppsToLaunchResponse:
+        """Get run IDs with pending messages."""
+        log(DEBUG, "SimulationIoServicer.ListAppsToLaunch")
+
+        # Initialize state connection
+        state = self.state_factory.state()
+
+        # Get IDs of runs in pending status
+        run_ids = state.get_run_ids(flwr_aid=None)
+        pending_run_ids = []
+        for run_id, status in state.get_run_status(run_ids).items():
+            if status.status == Status.PENDING:
+                pending_run_ids.append(run_id)
+
+        # Return run IDs
+        return ListAppsToLaunchResponse(run_ids=pending_run_ids)
+
+    def RequestToken(
+        self, request: RequestTokenRequest, context: grpc.ServicerContext
+    ) -> RequestTokenResponse:
+        """Request token."""
+        log(DEBUG, "SimulationIoServicer.RequestToken")
+
+        # Initialize state connection
+        state = self.state_factory.state()
+
+        # Attempt to create a token for the provided run ID
+        token = state.create_token(request.run_id)
+
+        # Return the token
+        return RequestTokenResponse(token=token or "")
+
+    def GetRun(
+        self, request: GetRunRequest, context: grpc.ServicerContext
+    ) -> GetRunResponse:
+        """Get run information."""
+        log(DEBUG, "SimulationIoServicer.GetRun")
+
+        # Init state
+        state = self.state_factory.state()
+
+        # Retrieve run information
+        run = state.get_run(request.run_id)
+
+        if run is None:
+            return GetRunResponse()
+
+        return GetRunResponse(run=run_to_proto(run))
+
+    def PullAppInputs(
+        self, request: PullAppInputsRequest, context: ServicerContext
+    ) -> PullAppInputsResponse:
         """Pull SimultionIo process inputs."""
         log(DEBUG, "SimultionIoServicer.SimultionIoInputs")
         # Init access to LinkState and Ffs
         state = self.state_factory.state()
         ffs = self.ffs_factory.ffs()
 
+        # Validate the token
+        run_id = self._verify_token(request.token, context)
+
         # Lock access to LinkState, preventing obtaining the same pending run_id
         with self.lock:
-            # Attempt getting the run_id of a pending run
-            run_id = state.get_pending_run_id()
-            # If there's no pending run, return an empty response
-            if run_id is None:
-                return PullSimulationInputsResponse()
-
             # Retrieve Context, Run and Fab for the run_id
             serverapp_ctxt = state.get_serverapp_context(run_id)
             run = state.get_run(run_id)
@@ -99,7 +155,7 @@ class SimulationIoServicer(simulationio_pb2_grpc.SimulationIoServicer):
                 # Update run status to STARTING
                 if state.update_run_status(run_id, RunStatus(Status.STARTING, "", "")):
                     log(INFO, "Starting run %d", run_id)
-                    return PullSimulationInputsResponse(
+                    return PullAppInputsResponse(
                         context=context_to_proto(serverapp_ctxt),
                         run=run_to_proto(run),
                         fab=fab_to_proto(fab),
@@ -109,11 +165,16 @@ class SimulationIoServicer(simulationio_pb2_grpc.SimulationIoServicer):
         # or if the status cannot be updated to STARTING
         raise RuntimeError(f"Failed to start run {run_id}")
 
-    def PushSimulationOutputs(
-        self, request: PushSimulationOutputsRequest, context: ServicerContext
-    ) -> PushSimulationOutputsResponse:
+    def PushAppOutputs(
+        self, request: PushAppOutputsRequest, context: ServicerContext
+    ) -> PushAppOutputsResponse:
         """Push Simulation process outputs."""
-        log(DEBUG, "SimultionIoServicer.PushSimulationOutputs")
+        log(DEBUG, "SimultionIoServicer.PushAppOutputs")
+
+        # Validate the token
+        run_id = self._verify_token(request.token, context)
+
+        # Init access to LinkState
         state = self.state_factory.state()
 
         # Abort if the run is not running
@@ -126,7 +187,10 @@ class SimulationIoServicer(simulationio_pb2_grpc.SimulationIoServicer):
         )
 
         state.set_serverapp_context(request.run_id, context_from_proto(request.context))
-        return PushSimulationOutputsResponse()
+
+        # Remove the token
+        state.delete_token(run_id)
+        return PushAppOutputsResponse()
 
     def UpdateRunStatus(
         self, request: UpdateRunStatusRequest, context: grpc.ServicerContext
@@ -208,3 +272,15 @@ class SimulationIoServicer(simulationio_pb2_grpc.SimulationIoServicer):
         )
 
         return SendAppHeartbeatResponse(success=success)
+
+    def _verify_token(self, token: str, context: grpc.ServicerContext) -> int:
+        """Verify the token and return the associated run ID."""
+        state = self.state_factory.state()
+        run_id = state.get_run_id_by_token(token)
+        if run_id is None or not state.verify_token(run_id, token):
+            context.abort(
+                grpc.StatusCode.PERMISSION_DENIED,
+                "Invalid token.",
+            )
+            raise RuntimeError("This line should never be reached.")
+        return run_id

flwr/server/superlink/utils.py

@@ -20,11 +20,7 @@ from typing import Optional, Union
 import grpc
 
 from flwr.common.constant import Status, SubStatus
-from flwr.common.inflatable import iterate_object_tree
 from flwr.common.typing import RunStatus
-from flwr.proto.fleet_pb2 import PushMessagesRequest  # pylint: disable=E0611
-from flwr.proto.message_pb2 import ObjectIDs  # pylint: disable=E0611
-from flwr.proto.serverappio_pb2 import PushInsMessagesRequest  # pylint: disable=E0611
 from flwr.server.superlink.linkstate import LinkState
 from flwr.supercore.object_store import ObjectStore
 
@@ -74,34 +70,3 @@ def abort_if(
     """Abort context if status of the provided `run_id` is in `abort_status_list`."""
     msg = check_abort(run_id, abort_status_list, state, store)
     abort_grpc_context(msg, context)
-
-
-def store_mapping_and_register_objects(
-    store: ObjectStore, request: Union[PushInsMessagesRequest, PushMessagesRequest]
-) -> dict[str, ObjectIDs]:
-    """Store Message object to descendants mapping and preregister objects."""
-    if not request.messages_list:
-        return {}
-
-    objects_to_push: dict[str, ObjectIDs] = {}
-
-    # Get run_id from the first message in the list
-    # All messages of a request should in the same run
-    run_id = request.messages_list[0].metadata.run_id
-
-    for object_tree in request.message_object_trees:
-        all_object_ids = [obj.object_id for obj in iterate_object_tree(object_tree)]
-        msg_object_id, descendant_ids = all_object_ids[-1], all_object_ids[:-1]
-        # Store mapping
-        store.set_message_descendant_ids(
-            msg_object_id=msg_object_id, descendant_ids=descendant_ids
-        )
-
-        # Preregister
-        object_ids_just_registered = store.preregister(run_id, object_tree)
-        # Keep track of objects that need to be pushed
-        objects_to_push[msg_object_id] = ObjectIDs(
-            object_ids=object_ids_just_registered
-        )
-
-    return objects_to_push

flwr/serverapp/__init__.py

@@ -13,3 +13,15 @@
 # limitations under the License.
 # ==============================================================================
 """Public Flower ServerApp APIs."""
+
+
+from flwr.server.grid import Grid
+from flwr.server.server_app import ServerApp
+
+from . import strategy
+
+__all__ = [
+    "Grid",
+    "ServerApp",
+    "strategy",
+]

flwr/serverapp/dp_fixed_clipping.py

@@ -0,0 +1,352 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Message-based Central differential privacy with fixed clipping.
+
+Papers: https://arxiv.org/abs/1712.07557, https://arxiv.org/abs/1710.06963
+"""
+
+from abc import ABC
+from collections import OrderedDict
+from collections.abc import Iterable
+from logging import INFO, WARNING
+from typing import Optional
+
+from flwr.common import Array, ArrayRecord, ConfigRecord, Message, MetricRecord, log
+from flwr.common.differential_privacy import (
+    add_gaussian_noise_inplace,
+    compute_clip_model_update,
+    compute_stdv,
+)
+from flwr.common.differential_privacy_constants import (
+    CLIENTS_DISCREPANCY_WARNING,
+    KEY_CLIPPING_NORM,
+)
+from flwr.server import Grid
+
+from .strategy import Strategy
+
+
+class DifferentialPrivacyFixedClippingBase(Strategy, ABC):
+    """Base class for DP strategies with fixed clipping.
+
+    This class contains common functionality shared between server-side and
+    client-side fixed clipping implementations.
+
+    Parameters
+    ----------
+    strategy : Strategy
+        The strategy to which DP functionalities will be added by this wrapper.
+    noise_multiplier : float
+        The noise multiplier for the Gaussian mechanism for model updates.
+        A value of 1.0 or higher is recommended for strong privacy.
+    clipping_norm : float
+        The value of the clipping norm.
+    num_sampled_clients : int
+        The number of clients that are sampled on each round.
+    """
+
+    # pylint: disable=too-many-arguments,too-many-instance-attributes
+    def __init__(
+        self,
+        strategy: Strategy,
+        noise_multiplier: float,
+        clipping_norm: float,
+        num_sampled_clients: int,
+    ) -> None:
+        super().__init__()
+
+        self.strategy = strategy
+
+        if noise_multiplier < 0:
+            raise ValueError("The noise multiplier should be a non-negative value.")
+
+        if clipping_norm <= 0:
+            raise ValueError("The clipping norm should be a positive value.")
+
+        if num_sampled_clients <= 0:
+            raise ValueError(
+                "The number of sampled clients should be a positive value."
+            )
+
+        self.noise_multiplier = noise_multiplier
+        self.clipping_norm = clipping_norm
+        self.num_sampled_clients = num_sampled_clients
+
+    def _validate_replies(self, replies: Iterable[Message]) -> bool:
+        """Validate replies and log errors/warnings.
+
+        Returns
+        -------
+        bool
+            True if replies are valid for aggregation, False otherwise.
+        """
+        num_errors = 0
+        num_replies_with_content = 0
+        for msg in replies:
+            if msg.has_error():
+                log(
+                    INFO,
+                    "Received error in reply from node %d: %s",
+                    msg.metadata.src_node_id,
+                    msg.error,
+                )
+                num_errors += 1
+            else:
+                num_replies_with_content += 1
+
+        # Errors are not allowed
+        if num_errors:
+            log(
+                INFO,
+                "aggregate_train: Some clients reported errors. Skipping aggregation.",
+            )
+            return False
+
+        log(
+            INFO,
+            "aggregate_train: Received %s results and %s failures",
+            num_replies_with_content,
+            num_errors,
+        )
+
+        if num_replies_with_content != self.num_sampled_clients:
+            log(
+                WARNING,
+                CLIENTS_DISCREPANCY_WARNING,
+                num_replies_with_content,
+                self.num_sampled_clients,
+            )
+
+        return True
+
+    def _add_noise_to_aggregated_arrays(
+        self, aggregated_arrays: ArrayRecord
+    ) -> ArrayRecord:
+        """Add Gaussian noise to aggregated arrays.
+
+        Parameters
+        ----------
+        aggregated_arrays : ArrayRecord
+            The aggregated arrays to add noise to.
+
+        Returns
+        -------
+        ArrayRecord
+            The aggregated arrays with noise added.
+        """
+        aggregated_ndarrays = aggregated_arrays.to_numpy_ndarrays()
+        stdv = compute_stdv(
+            self.noise_multiplier, self.clipping_norm, self.num_sampled_clients
+        )
+        add_gaussian_noise_inplace(aggregated_ndarrays, stdv)
+
+        log(
+            INFO,
+            "aggregate_fit: central DP noise with %.4f stdev added",
+            stdv,
+        )
+
+        return ArrayRecord(
+            OrderedDict(
+                {
+                    k: Array(v)
+                    for k, v in zip(aggregated_arrays.keys(), aggregated_ndarrays)
+                }
+            )
+        )
+
+    def configure_evaluate(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of federated evaluation."""
+        return self.strategy.configure_evaluate(server_round, arrays, config, grid)
+
+    def aggregate_evaluate(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> Optional[MetricRecord]:
+        """Aggregate MetricRecords in the received Messages."""
+        return self.strategy.aggregate_evaluate(server_round, replies)
+
+    def summary(self) -> None:
+        """Log summary configuration of the strategy."""
+        self.strategy.summary()
+
+
+class DifferentialPrivacyServerSideFixedClipping(DifferentialPrivacyFixedClippingBase):
+    """Strategy wrapper for central DP with server-side fixed clipping.
+
+    Parameters
+    ----------
+    strategy : Strategy
+        The strategy to which DP functionalities will be added by this wrapper.
+    noise_multiplier : float
+        The noise multiplier for the Gaussian mechanism for model updates.
+        A value of 1.0 or higher is recommended for strong privacy.
+    clipping_norm : float
+        The value of the clipping norm.
+    num_sampled_clients : int
+        The number of clients that are sampled on each round.
+
+    Examples
+    --------
+    Create a strategy::
+
+        strategy = fl.serverapp.FedAvg( ... )
+
+    Wrap the strategy with the `DifferentialPrivacyServerSideFixedClipping` wrapper::
+
+        dp_strategy = DifferentialPrivacyServerSideFixedClipping(
+            strategy, cfg.noise_multiplier, cfg.clipping_norm, cfg.num_sampled_clients
+        )
+    """
+
+    def __init__(
+        self,
+        strategy: Strategy,
+        noise_multiplier: float,
+        clipping_norm: float,
+        num_sampled_clients: int,
+    ) -> None:
+        super().__init__(strategy, noise_multiplier, clipping_norm, num_sampled_clients)
+        self.current_arrays: ArrayRecord = ArrayRecord()
+
+    def __repr__(self) -> str:
+        """Compute a string representation of the strategy."""
+        return "Differential Privacy Strategy Wrapper (Server-Side Fixed Clipping)"
+
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of training."""
+        self.current_arrays = arrays
+        return self.strategy.configure_train(server_round, arrays, config, grid)
+
+    def aggregate_train(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate ArrayRecords and MetricRecords in the received Messages."""
+        if not self._validate_replies(replies):
+            return None, None
+
+        # Clip arrays in replies
+        current_ndarrays = self.current_arrays.to_numpy_ndarrays()
+        for reply in replies:
+            for arr_name, record in reply.content.array_records.items():
+                # Clip
+                reply_ndarrays = record.to_numpy_ndarrays()
+                compute_clip_model_update(
+                    param1=reply_ndarrays,
+                    param2=current_ndarrays,
+                    clipping_norm=self.clipping_norm,
+                )
+                # Replace content while preserving keys
+                reply.content[arr_name] = ArrayRecord(
+                    OrderedDict(
+                        {k: Array(v) for k, v in zip(record.keys(), reply_ndarrays)}
+                    )
+                )
+            log(
+                INFO,
+                "aggregate_fit: parameters are clipped by value: %.4f.",
+                self.clipping_norm,
+            )
+
+        # Pass the new parameters for aggregation
+        aggregated_arrays, aggregated_metrics = self.strategy.aggregate_train(
+            server_round, replies
+        )
+
+        # Add Gaussian noise to the aggregated arrays
+        if aggregated_arrays:
+            aggregated_arrays = self._add_noise_to_aggregated_arrays(aggregated_arrays)
+
+        return aggregated_arrays, aggregated_metrics
+
+
+class DifferentialPrivacyClientSideFixedClipping(DifferentialPrivacyFixedClippingBase):
+    """Strategy wrapper for central DP with client-side fixed clipping.
+
+    Use `fixedclipping_mod` modifier at the client side.
+
+    In comparison to `DifferentialPrivacyServerSideFixedClipping`,
+    which performs clipping on the server-side,
+    `DifferentialPrivacyClientSideFixedClipping` expects clipping to happen
+    on the client-side, usually by using the built-in `fixedclipping_mod`.
+
+    Parameters
+    ----------
+    strategy : Strategy
+        The strategy to which DP functionalities will be added by this wrapper.
+    noise_multiplier : float
+        The noise multiplier for the Gaussian mechanism for model updates.
+        A value of 1.0 or higher is recommended for strong privacy.
+    clipping_norm : float
+        The value of the clipping norm.
+    num_sampled_clients : int
+        The number of clients that are sampled on each round.
+
+    Examples
+    --------
+    Create a strategy::
+
+        strategy = fl.serverapp.FedAvg(...)
+
+    Wrap the strategy with the `DifferentialPrivacyClientSideFixedClipping` wrapper::
+
+        dp_strategy = DifferentialPrivacyClientSideFixedClipping(
+            strategy, cfg.noise_multiplier, cfg.clipping_norm, cfg.num_sampled_clients
+        )
+
+    On the client, add the `fixedclipping_mod` to the client-side mods::
+
+        app = fl.client.ClientApp(mods=[fixedclipping_mod])
+    """
+
+    def __repr__(self) -> str:
+        """Compute a string representation of the strategy."""
+        return "Differential Privacy Strategy Wrapper (Client-Side Fixed Clipping)"
+
+    def configure_train(
+        self, server_round: int, arrays: ArrayRecord, config: ConfigRecord, grid: Grid
+    ) -> Iterable[Message]:
+        """Configure the next round of training."""
+        # Inject clipping norm in config
+        config[KEY_CLIPPING_NORM] = self.clipping_norm
+        # Call parent method
+        return self.strategy.configure_train(server_round, arrays, config, grid)
+
+    def aggregate_train(
+        self,
+        server_round: int,
+        replies: Iterable[Message],
+    ) -> tuple[Optional[ArrayRecord], Optional[MetricRecord]]:
+        """Aggregate ArrayRecords and MetricRecords in the received Messages."""
+        if not self._validate_replies(replies):
+            return None, None
+
+        # Aggregate
+        aggregated_arrays, aggregated_metrics = self.strategy.aggregate_train(
+            server_round, replies
+        )
+
+        # Add Gaussian noise to the aggregated arrays
+        if aggregated_arrays:
+            aggregated_arrays = self._add_noise_to_aggregated_arrays(aggregated_arrays)
+
+        return aggregated_arrays, aggregated_metrics

flwr/serverapp/exception.py

@@ -0,0 +1,38 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""Flower ServerApp exceptions."""
+
+
+from flwr.app.exception import AppExitException
+from flwr.common.exit import ExitCode
+
+
+class InconsistentMessageReplies(AppExitException):
+    """Exception triggered when replies are inconsistent and therefore aggregation must
+    be skipped."""
+
+    exit_code = ExitCode.SERVERAPP_STRATEGY_PRECONDITION_UNMET
+
+    def __init__(self, reason: str):
+        super().__init__(reason)
+
+
+class AggregationError(AppExitException):
+    """Exception triggered when aggregation fails."""
+
+    exit_code = ExitCode.SERVERAPP_STRATEGY_AGGREGATION_ERROR
+
+    def __init__(self, reason: str):
+        super().__init__(reason)

flwr/serverapp/strategy/__init__.py

@@ -0,0 +1,38 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""ServerApp strategies."""
+
+
+from .dp_fixed_clipping import (
+    DifferentialPrivacyClientSideFixedClipping,
+    DifferentialPrivacyServerSideFixedClipping,
+)
+from .fedadagrad import FedAdagrad
+from .fedadam import FedAdam
+from .fedavg import FedAvg
+from .fedyogi import FedYogi
+from .result import Result
+from .strategy import Strategy
+
+__all__ = [
+    "DifferentialPrivacyClientSideFixedClipping",
+    "DifferentialPrivacyServerSideFixedClipping",
+    "FedAdagrad",
+    "FedAdam",
+    "FedAvg",
+    "FedYogi",
+    "Result",
+    "Strategy",
+]