flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.15.0.dev20250114__py3-none-any.whl

flwr/client/clientapp/clientappio_servicer.py

@@ -0,0 +1,244 @@
+# Copyright 2024 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.
+# ==============================================================================
+"""ClientAppIo API servicer."""
+
+
+from dataclasses import dataclass
+from logging import DEBUG, ERROR
+from typing import Optional, cast
+
+import grpc
+
+from flwr.common import Context, Message, typing
+from flwr.common.logger import log
+from flwr.common.serde import (
+    clientappstatus_to_proto,
+    context_from_proto,
+    context_to_proto,
+    fab_to_proto,
+    message_from_proto,
+    message_to_proto,
+    run_to_proto,
+)
+from flwr.common.typing import Fab, Run
+
+# pylint: disable=E0611
+from flwr.proto import clientappio_pb2_grpc
+from flwr.proto.clientappio_pb2 import (  # pylint: disable=E0401
+    GetTokenRequest,
+    GetTokenResponse,
+    PullClientAppInputsRequest,
+    PullClientAppInputsResponse,
+    PushClientAppOutputsRequest,
+    PushClientAppOutputsResponse,
+)
+
+
+@dataclass
+class ClientAppInputs:
+    """Specify the inputs to the ClientApp."""
+
+    message: Message
+    context: Context
+    run: Run
+    fab: Optional[Fab]
+    token: int
+
+
+@dataclass
+class ClientAppOutputs:
+    """Specify the outputs from the ClientApp."""
+
+    message: Message
+    context: Context
+
+
+# pylint: disable=C0103,W0613,W0201
+class ClientAppIoServicer(clientappio_pb2_grpc.ClientAppIoServicer):
+    """ClientAppIo API servicer."""
+
+    def __init__(self) -> None:
+        self.clientapp_input: Optional[ClientAppInputs] = None
+        self.clientapp_output: Optional[ClientAppOutputs] = None
+        self.token_returned: bool = False
+        self.inputs_returned: bool = False
+
+    def GetToken(
+        self, request: GetTokenRequest, context: grpc.ServicerContext
+    ) -> GetTokenResponse:
+        """Get token."""
+        log(DEBUG, "ClientAppIo.GetToken")
+
+        # Fail if no ClientAppInputs are available
+        if self.clientapp_input is None:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                "No inputs available.",
+            )
+        clientapp_input = cast(ClientAppInputs, self.clientapp_input)
+
+        # Fail if token was already returned in a previous call
+        if self.token_returned:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                "Token already returned. A token can be returned only once.",
+            )
+
+        # If
+        # - ClientAppInputs is set, and
+        # - token hasn't been returned before,
+        # return token
+        self.token_returned = True
+        return GetTokenResponse(token=clientapp_input.token)
+
+    def PullClientAppInputs(
+        self, request: PullClientAppInputsRequest, context: grpc.ServicerContext
+    ) -> PullClientAppInputsResponse:
+        """Pull Message, Context, and Run."""
+        log(DEBUG, "ClientAppIo.PullClientAppInputs")
+
+        # Fail if no ClientAppInputs are available
+        if self.clientapp_input is None:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                "No inputs available.",
+            )
+        clientapp_input = cast(ClientAppInputs, self.clientapp_input)
+
+        # Fail if token wasn't returned in a previous call
+        if not self.token_returned:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                "Token hasn't been returned."
+                "Token must be returned before can be returned only once.",
+            )
+
+        # Fail if token isn't matching
+        if request.token != clientapp_input.token:
+            context.abort(
+                grpc.StatusCode.INVALID_ARGUMENT,
+                "Mismatch between ClientApp and SuperNode token",
+            )
+
+        # Success
+        self.inputs_returned = True
+        return PullClientAppInputsResponse(
+            message=message_to_proto(clientapp_input.message),
+            context=context_to_proto(clientapp_input.context),
+            run=run_to_proto(clientapp_input.run),
+            fab=fab_to_proto(clientapp_input.fab) if clientapp_input.fab else None,
+        )
+
+    def PushClientAppOutputs(
+        self, request: PushClientAppOutputsRequest, context: grpc.ServicerContext
+    ) -> PushClientAppOutputsResponse:
+        """Push Message and Context."""
+        log(DEBUG, "ClientAppIo.PushClientAppOutputs")
+
+        # Fail if no ClientAppInputs are available
+        if not self.clientapp_input:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                "No inputs available.",
+            )
+        clientapp_input = cast(ClientAppInputs, self.clientapp_input)
+
+        # Fail if token wasn't returned in a previous call
+        if not self.token_returned:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                "Token hasn't been returned."
+                "Token must be returned before can be returned only once.",
+            )
+
+        # Fail if inputs weren't delivered in a previous call
+        if not self.inputs_returned:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                "Inputs haven't been delivered."
+                "Inputs must be delivered before can be returned only once.",
+            )
+
+        # Fail if token isn't matching
+        if request.token != clientapp_input.token:
+            context.abort(
+                grpc.StatusCode.INVALID_ARGUMENT,
+                "Mismatch between ClientApp and SuperNode token",
+            )
+
+        # Preconditions met
+        try:
+            # Update Message and Context
+            self.clientapp_output = ClientAppOutputs(
+                message=message_from_proto(request.message),
+                context=context_from_proto(request.context),
+            )
+
+            # Set status
+            code = typing.ClientAppOutputCode.SUCCESS
+            status = typing.ClientAppOutputStatus(code=code, message="Success")
+        except Exception as e:  # pylint: disable=broad-exception-caught
+            log(ERROR, "ClientApp failed to push message to SuperNode, %s", e)
+            code = typing.ClientAppOutputCode.UNKNOWN_ERROR
+            status = typing.ClientAppOutputStatus(code=code, message="Unkonwn error")
+
+        # Return status to ClientApp process
+        proto_status = clientappstatus_to_proto(status=status)
+        return PushClientAppOutputsResponse(status=proto_status)
+
+    def set_inputs(
+        self, clientapp_input: ClientAppInputs, token_returned: bool
+    ) -> None:
+        """Set ClientApp inputs.
+
+        Parameters
+        ----------
+        clientapp_input : ClientAppInputs
+            The inputs to the ClientApp.
+        token_returned : bool
+            A boolean indicating if the token has been returned.
+            Set to `True` when passing the token to `flwr-clientap`
+            and `False` otherwise.
+        """
+        if (
+            self.clientapp_input is not None
+            or self.clientapp_output is not None
+            or self.token_returned
+        ):
+            raise ValueError(
+                "ClientAppInputs and ClientAppOutputs must not be set before "
+                "calling `set_inputs`."
+            )
+        log(DEBUG, "ClientAppInputs set (token: %s)", clientapp_input.token)
+        self.clientapp_input = clientapp_input
+        self.token_returned = token_returned
+
+    def has_outputs(self) -> bool:
+        """Check if ClientAppOutputs are available."""
+        return self.clientapp_output is not None
+
+    def get_outputs(self) -> ClientAppOutputs:
+        """Get ClientApp outputs."""
+        if self.clientapp_output is None:
+            raise ValueError("ClientAppOutputs not set before calling `get_outputs`.")
+
+        # Set outputs to a local variable and clear state
+        output: ClientAppOutputs = self.clientapp_output
+        self.clientapp_input = None
+        self.clientapp_output = None
+        self.token_returned = False
+        self.inputs_returned = False
+
+        return output

flwr/client/clientapp/utils.py

@@ -0,0 +1,115 @@
+# Copyright 2024 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 ClientApp loading utils."""
+
+
+from logging import DEBUG
+from pathlib import Path
+from typing import Callable, Optional
+
+from flwr.client.client_app import ClientApp, LoadClientAppError
+from flwr.common.config import (
+    get_flwr_dir,
+    get_metadata_from_config,
+    get_project_config,
+    get_project_dir,
+)
+from flwr.common.logger import log
+from flwr.common.object_ref import load_app, validate
+
+
+def get_load_client_app_fn(
+    default_app_ref: str,
+    app_path: Optional[str],
+    multi_app: bool,
+    flwr_dir: Optional[str] = None,
+) -> Callable[[str, str, str], ClientApp]:
+    """Get the load_client_app_fn function.
+
+    If `multi_app` is True, this function loads the specified ClientApp
+    based on `fab_id` and `fab_version`. If `fab_id` is empty, a default
+    ClientApp will be loaded.
+
+    If `multi_app` is False, it ignores `fab_id` and `fab_version` and
+    loads a default ClientApp.
+    """
+    if not multi_app:
+        log(
+            DEBUG,
+            "Flower SuperNode will load and validate ClientApp `%s`",
+            default_app_ref,
+        )
+
+        valid, error_msg = validate(default_app_ref, project_dir=app_path)
+        if not valid and error_msg:
+            raise LoadClientAppError(error_msg) from None
+
+    def _load(fab_id: str, fab_version: str, fab_hash: str) -> ClientApp:
+        runtime_app_dir = Path(app_path if app_path else "").absolute()
+        # If multi-app feature is disabled
+        if not multi_app:
+            # Set app reference
+            client_app_ref = default_app_ref
+        # If multi-app feature is enabled but app directory is provided.
+        # `fab_hash` is not required since the app is loaded from `runtime_app_dir`.
+        elif app_path is not None:
+            config = get_project_config(runtime_app_dir)
+            this_fab_version, this_fab_id = get_metadata_from_config(config)
+
+            if this_fab_version != fab_version or this_fab_id != fab_id:
+                raise LoadClientAppError(
+                    f"FAB ID or version mismatch: Expected FAB ID '{this_fab_id}' and "
+                    f"FAB version '{this_fab_version}', but received FAB ID '{fab_id}' "
+                    f"and FAB version '{fab_version}'.",
+                ) from None
+
+            # log(WARN, "FAB ID is not provided; the default ClientApp will be loaded.")
+
+            # Set app reference
+            client_app_ref = config["tool"]["flwr"]["app"]["components"]["clientapp"]
+        # If multi-app feature is enabled
+        else:
+            try:
+                runtime_app_dir = get_project_dir(
+                    fab_id, fab_version, fab_hash, get_flwr_dir(flwr_dir)
+                )
+                config = get_project_config(runtime_app_dir)
+            except Exception as e:
+                raise LoadClientAppError(
+                    "Failed to load ClientApp."
+                    "Possible reasons for error include mismatched "
+                    "`fab_id`, `fab_version`, or `fab_hash` in "
+                    f"{str(get_flwr_dir(flwr_dir).resolve())}."
+                ) from e
+
+            # Set app reference
+            client_app_ref = config["tool"]["flwr"]["app"]["components"]["clientapp"]
+
+        # Load ClientApp
+        log(
+            DEBUG,
+            "Loading ClientApp `%s`",
+            client_app_ref,
+        )
+        client_app = load_app(client_app_ref, LoadClientAppError, runtime_app_dir)
+
+        if not isinstance(client_app, ClientApp):
+            raise LoadClientAppError(
+                f"Attribute {client_app_ref} is not of type {ClientApp}",
+            ) from None
+
+        return client_app
+
+    return _load

flwr/client/dpfedavg_numpy_client.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2022 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.
@@ -16,7 +16,6 @@
 
 
 import copy
-from typing import Dict, Tuple
 
 import numpy as np
 
@@ -39,7 +38,7 @@ class DPFedAvgNumPyClient(NumPyClient):
         super().__init__()
         self.client = client
 
-    def get_properties(self, config: Config) -> Dict[str, Scalar]:
+    def get_properties(self, config: Config) -> dict[str, Scalar]:
         """Get client properties using the given Numpy client.
 
         Parameters
@@ -58,7 +57,7 @@ class DPFedAvgNumPyClient(NumPyClient):
         """
         return self.client.get_properties(config)
 
-    def get_parameters(self, config: Dict[str, Scalar]) -> NDArrays:
+    def get_parameters(self, config: dict[str, Scalar]) -> NDArrays:
         """Return the current local model parameters.
 
         Parameters
@@ -76,8 +75,8 @@ class DPFedAvgNumPyClient(NumPyClient):
         return self.client.get_parameters(config)
 
     def fit(
-        self, parameters: NDArrays, config: Dict[str, Scalar]
-    ) -> Tuple[NDArrays, int, Dict[str, Scalar]]:
+        self, parameters: NDArrays, config: dict[str, Scalar]
+    ) -> tuple[NDArrays, int, dict[str, Scalar]]:
         """Train the provided parameters using the locally held dataset.
 
         This method first updates the local model using the original parameters
@@ -153,8 +152,8 @@ class DPFedAvgNumPyClient(NumPyClient):
         return updated_params, num_examples, metrics
 
     def evaluate(
-        self, parameters: NDArrays, config: Dict[str, Scalar]
-    ) -> Tuple[float, int, Dict[str, Scalar]]:
+        self, parameters: NDArrays, config: dict[str, Scalar]
+    ) -> tuple[float, int, dict[str, Scalar]]:
         """Evaluate the provided parameters using the locally held dataset.
 
         Parameters

flwr/client/grpc_adapter_client/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2024 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.
+# ==============================================================================
+"""Client-side part of the GrpcAdapter transport layer."""

flwr/client/grpc_adapter_client/connection.py

@@ -0,0 +1,98 @@
+# Copyright 2024 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.
+# ==============================================================================
+"""Contextmanager for a GrpcAdapter channel to the Flower server."""
+
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from logging import ERROR
+from typing import Callable, Optional, Union
+
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from flwr.client.grpc_rere_client.connection import grpc_request_response
+from flwr.client.grpc_rere_client.grpc_adapter import GrpcAdapter
+from flwr.common import GRPC_MAX_MESSAGE_LENGTH
+from flwr.common.logger import log
+from flwr.common.message import Message
+from flwr.common.retry_invoker import RetryInvoker
+from flwr.common.typing import Fab, Run
+
+
+@contextmanager
+def grpc_adapter(  # pylint: disable=R0913,too-many-positional-arguments
+    server_address: str,
+    insecure: bool,
+    retry_invoker: RetryInvoker,
+    max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,  # pylint: disable=W0613
+    root_certificates: Optional[Union[bytes, str]] = None,
+    authentication_keys: Optional[  # pylint: disable=unused-argument
+        tuple[ec.EllipticCurvePrivateKey, ec.EllipticCurvePublicKey]
+    ] = None,
+) -> Iterator[
+    tuple[
+        Callable[[], Optional[Message]],
+        Callable[[Message], None],
+        Optional[Callable[[], Optional[int]]],
+        Optional[Callable[[], None]],
+        Optional[Callable[[int], Run]],
+        Optional[Callable[[str, int], Fab]],
+    ]
+]:
+    """Primitives for request/response-based interaction with a server via GrpcAdapter.
+
+    Parameters
+    ----------
+    server_address : str
+        The IPv6 address of the server with `http://` or `https://`.
+        If the Flower server runs on the same machine
+        on port 8080, then `server_address` would be `"http://[::]:8080"`.
+    insecure : bool
+        Starts an insecure gRPC connection when True. Enables HTTPS connection
+        when False, using system certificates if `root_certificates` is None.
+    retry_invoker: RetryInvoker
+        `RetryInvoker` object that will try to reconnect the client to the server
+        after gRPC errors. If None, the client will only try to
+        reconnect once after a failure.
+    max_message_length : int
+        Ignored, only present to preserve API-compatibility.
+    root_certificates : Optional[Union[bytes, str]] (default: None)
+        Path of the root certificate. If provided, a secure
+        connection using the certificates will be established to an SSL-enabled
+        Flower server. Bytes won't work for the REST API.
+    authentication_keys : Optional[Tuple[PrivateKey, PublicKey]] (default: None)
+        Client authentication is not supported for this transport type.
+
+    Returns
+    -------
+    receive : Callable
+    send : Callable
+    create_node : Optional[Callable]
+    delete_node : Optional[Callable]
+    get_run : Optional[Callable]
+    get_fab : Optional[Callable]
+    """
+    if authentication_keys is not None:
+        log(ERROR, "Client authentication is not supported for this transport type.")
+    with grpc_request_response(
+        server_address=server_address,
+        insecure=insecure,
+        retry_invoker=retry_invoker,
+        max_message_length=max_message_length,
+        root_certificates=root_certificates,
+        authentication_keys=None,  # Authentication is not supported
+        adapter_cls=GrpcAdapter,
+    ) as conn:
+        yield conn

flwr/client/grpc_client/connection.py

@@ -16,13 +16,17 @@
 
 
 import uuid
+from collections.abc import Iterator
 from contextlib import contextmanager
-from logging import DEBUG
+from logging import DEBUG, ERROR
 from pathlib import Path
 from queue import Queue
-from typing import Callable, Iterator, Optional, Tuple, Union, cast
+from typing import Callable, Optional, Union, cast
+
+from cryptography.hazmat.primitives.asymmetric import ec
 
 from flwr.common import (
+    DEFAULT_TTL,
     GRPC_MAX_MESSAGE_LENGTH,
     ConfigsRecord,
     Message,
@@ -35,6 +39,7 @@ from flwr.common.constant import MessageType, MessageTypeLegacy
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
 from flwr.common.retry_invoker import RetryInvoker
+from flwr.common.typing import Fab, Run
 from flwr.proto.transport_pb2 import (  # pylint: disable=E0611
     ClientMessage,
     Reason,
@@ -55,18 +60,23 @@ def on_channel_state_change(channel_connectivity: str) -> None:
 
 
 @contextmanager
-def grpc_connection(  # pylint: disable=R0915
+def grpc_connection(  # pylint: disable=R0913,R0915,too-many-positional-arguments
     server_address: str,
     insecure: bool,
     retry_invoker: RetryInvoker,  # pylint: disable=unused-argument
     max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,
     root_certificates: Optional[Union[bytes, str]] = None,
+    authentication_keys: Optional[  # pylint: disable=unused-argument
+        tuple[ec.EllipticCurvePrivateKey, ec.EllipticCurvePublicKey]
+    ] = None,
 ) -> Iterator[
-    Tuple[
+    tuple[
         Callable[[], Optional[Message]],
         Callable[[Message], None],
+        Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
-        Optional[Callable[[], None]],
+        Optional[Callable[[int], Run]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Establish a gRPC connection to a gRPC server.
@@ -94,6 +104,8 @@ def grpc_connection(  # pylint: disable=R0915
         The PEM-encoded root certificates as a byte string or a path string.
         If provided, a secure connection using the certificates will be
         established to an SSL-enabled Flower server.
+    authentication_keys : Optional[Tuple[PrivateKey, PublicKey]] (default: None)
+        Client authentication is not supported for this transport type.
 
     Returns
     -------
@@ -116,6 +128,8 @@ def grpc_connection(  # pylint: disable=R0915
     """
     if isinstance(root_certificates, str):
         root_certificates = Path(root_certificates).read_bytes()
+    if authentication_keys is not None:
+        log(ERROR, "Client authentication is not supported for this transport type.")
 
     channel = create_channel(
         server_address=server_address,
@@ -180,7 +194,7 @@ def grpc_connection(  # pylint: disable=R0915
                 dst_node_id=0,
                 reply_to_message="",
                 group_id="",
-                ttl="",
+                ttl=DEFAULT_TTL,
                 message_type=message_type,
             ),
             content=recordset,
@@ -223,7 +237,7 @@ def grpc_connection(  # pylint: disable=R0915
 
     try:
         # Yield methods
-        yield (receive, send, None, None)
+        yield (receive, send, None, None, None, None)
     finally:
         # Make sure to have a final
         channel.close()

flwr/client/grpc_rere_client/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2023 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.