flwr-nightly 1.9.0.dev20240531__py3-none-any.whl → 1.10.0.dev20240619__py3-none-any.whl

flwr/client/grpc_rere_client/grpc_adapter.py

@@ -0,0 +1,133 @@
+# 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.
+# ==============================================================================
+"""GrpcAdapter implementation."""
+
+
+import sys
+from logging import DEBUG
+from typing import Any, Type, TypeVar, cast
+
+import grpc
+from google.protobuf.message import Message as GrpcMessage
+
+from flwr.common import log
+from flwr.common.constant import (
+    GRPC_ADAPTER_METADATA_FLOWER_VERSION_KEY,
+    GRPC_ADAPTER_METADATA_SHOULD_EXIT_KEY,
+)
+from flwr.common.version import package_version
+from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
+    CreateNodeRequest,
+    CreateNodeResponse,
+    DeleteNodeRequest,
+    DeleteNodeResponse,
+    PingRequest,
+    PingResponse,
+    PullTaskInsRequest,
+    PullTaskInsResponse,
+    PushTaskResRequest,
+    PushTaskResResponse,
+)
+from flwr.proto.grpcadapter_pb2 import MessageContainer  # pylint: disable=E0611
+from flwr.proto.grpcadapter_pb2_grpc import GrpcAdapterStub
+from flwr.proto.run_pb2 import GetRunRequest, GetRunResponse  # pylint: disable=E0611
+
+T = TypeVar("T", bound=GrpcMessage)
+
+
+class GrpcAdapter:
+    """Adapter class to send and receive gRPC messages via the ``GrpcAdapterStub``.
+
+    This class utilizes the ``GrpcAdapterStub`` to send and receive gRPC messages
+    which are defined and used by the Fleet API, as defined in ``fleet.proto``.
+    """
+
+    def __init__(self, channel: grpc.Channel) -> None:
+        self.stub = GrpcAdapterStub(channel)
+
+    def _send_and_receive(
+        self, request: GrpcMessage, response_type: Type[T], **kwargs: Any
+    ) -> T:
+        # Serialize request
+        container_req = MessageContainer(
+            metadata={GRPC_ADAPTER_METADATA_FLOWER_VERSION_KEY: package_version},
+            grpc_message_name=request.__class__.__qualname__,
+            grpc_message_content=request.SerializeToString(),
+        )
+
+        # Send via the stub
+        container_res = cast(
+            MessageContainer, self.stub.SendReceive(container_req, **kwargs)
+        )
+
+        # Handle control message
+        should_exit = (
+            container_res.metadata.get(GRPC_ADAPTER_METADATA_SHOULD_EXIT_KEY, "false")
+            == "true"
+        )
+        if should_exit:
+            log(
+                DEBUG,
+                'Received shutdown signal: exit flag is set to ``"true"``. Exiting...',
+            )
+            sys.exit(0)
+
+        # Check the grpc_message_name of the response
+        if container_res.grpc_message_name != response_type.__qualname__:
+            raise ValueError(
+                f"Invalid grpc_message_name. Expected {response_type.__qualname__}"
+                f", but got {container_res.grpc_message_name}."
+            )
+
+        # Deserialize response
+        response = response_type()
+        response.ParseFromString(container_res.grpc_message_content)
+        return response
+
+    def CreateNode(  # pylint: disable=C0103
+        self, request: CreateNodeRequest, **kwargs: Any
+    ) -> CreateNodeResponse:
+        """."""
+        return self._send_and_receive(request, CreateNodeResponse, **kwargs)
+
+    def DeleteNode(  # pylint: disable=C0103
+        self, request: DeleteNodeRequest, **kwargs: Any
+    ) -> DeleteNodeResponse:
+        """."""
+        return self._send_and_receive(request, DeleteNodeResponse, **kwargs)
+
+    def Ping(  # pylint: disable=C0103
+        self, request: PingRequest, **kwargs: Any
+    ) -> PingResponse:
+        """."""
+        return self._send_and_receive(request, PingResponse, **kwargs)
+
+    def PullTaskIns(  # pylint: disable=C0103
+        self, request: PullTaskInsRequest, **kwargs: Any
+    ) -> PullTaskInsResponse:
+        """."""
+        return self._send_and_receive(request, PullTaskInsResponse, **kwargs)
+
+    def PushTaskRes(  # pylint: disable=C0103
+        self, request: PushTaskResRequest, **kwargs: Any
+    ) -> PushTaskResResponse:
+        """."""
+        return self._send_and_receive(request, PushTaskResResponse, **kwargs)
+
+    def GetRun(  # pylint: disable=C0103
+        self, request: GetRunRequest, **kwargs: Any
+    ) -> GetRunResponse:
+        """."""
+        return self._send_and_receive(request, GetRunResponse, **kwargs)

flwr/client/mod/__init__.py

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Mods."""
+"""Flower Built-in Mods."""
 
 
 from .centraldp_mods import adaptiveclipping_mod, fixedclipping_mod
@@ -22,12 +22,12 @@ from .secure_aggregation import secagg_mod, secaggplus_mod
 from .utils import make_ffn
 
 __all__ = [
+    "LocalDpMod",
     "adaptiveclipping_mod",
     "fixedclipping_mod",
-    "LocalDpMod",
     "make_ffn",
-    "secagg_mod",
-    "secaggplus_mod",
     "message_size_mod",
     "parameters_size_mod",
+    "secagg_mod",
+    "secaggplus_mod",
 ]

flwr/client/rest_client/connection.py

@@ -46,8 +46,6 @@ from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     CreateNodeResponse,
     DeleteNodeRequest,
     DeleteNodeResponse,
-    GetRunRequest,
-    GetRunResponse,
     PingRequest,
     PingResponse,
     PullTaskInsRequest,
@@ -56,6 +54,7 @@ from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     PushTaskResResponse,
 )
 from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
+from flwr.proto.run_pb2 import GetRunRequest, GetRunResponse  # pylint: disable=E0611
 from flwr.proto.task_pb2 import TaskIns  # pylint: disable=E0611
 
 try:
@@ -118,10 +117,16 @@ def http_request_response(  # pylint: disable=,R0913, R0914, R0915
         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, send : Callable, Callable
+    receive : Callable
+    send : Callable
+    create_node : Optional[Callable]
+    delete_node : Optional[Callable]
+    get_run : Optional[Callable]
     """
     log(
         WARN,
@@ -146,6 +151,8 @@ def http_request_response(  # pylint: disable=,R0913, R0914, R0915
             "For the REST API, the root certificates "
             "must be provided as a string path to the client.",
         )
+    if authentication_keys is not None:
+        log(ERROR, "Client authentication is not supported for this transport type.")
 
     # Shared variables for inner functions
     metadata: Optional[Metadata] = None

flwr/client/supernode/app.py

@@ -29,12 +29,20 @@ from cryptography.hazmat.primitives.serialization import (
 
 from flwr.client.client_app import ClientApp, LoadClientAppError
 from flwr.common import EventType, event
+from flwr.common.config import get_flwr_dir, get_project_config, get_project_dir
+from flwr.common.constant import (
+    TRANSPORT_TYPE_GRPC_ADAPTER,
+    TRANSPORT_TYPE_GRPC_RERE,
+    TRANSPORT_TYPE_REST,
+)
 from flwr.common.exit_handlers import register_exit_handlers
-from flwr.common.logger import log
+from flwr.common.logger import log, warn_deprecated_feature
 from flwr.common.object_ref import load_app, validate
 
 from ..app import _start_client_internal
 
+ADDRESS_FLEET_API_GRPC_RERE = "0.0.0.0:9092"
+
 
 def run_supernode() -> None:
     """Run Flower SuperNode."""
@@ -42,11 +50,23 @@ def run_supernode() -> None:
 
     event(EventType.RUN_SUPERNODE_ENTER)
 
-    _ = _parse_args_run_supernode().parse_args()
+    args = _parse_args_run_supernode().parse_args()
+
+    _warn_deprecated_server_arg(args)
+
+    root_certificates = _get_certificates(args)
+    load_fn = _get_load_client_app_fn(args, multi_app=True)
+    authentication_keys = _try_setup_client_authentication(args)
 
-    log(
-        DEBUG,
-        "Flower SuperNode starting...",
+    _start_client_internal(
+        server_address=args.superlink,
+        load_client_app_fn=load_fn,
+        transport=args.transport,
+        root_certificates=root_certificates,
+        insecure=args.insecure,
+        authentication_keys=authentication_keys,
+        max_retries=args.max_retries,
+        max_wait_time=args.max_wait_time,
     )
 
     # Graceful shutdown
@@ -63,19 +83,16 @@ def run_client_app() -> None:
 
     args = _parse_args_run_client_app().parse_args()
 
+    _warn_deprecated_server_arg(args)
+
     root_certificates = _get_certificates(args)
-    log(
-        DEBUG,
-        "Flower will load ClientApp `%s`",
-        getattr(args, "client-app"),
-    )
-    load_fn = _get_load_client_app_fn(args)
+    load_fn = _get_load_client_app_fn(args, multi_app=False)
     authentication_keys = _try_setup_client_authentication(args)
 
     _start_client_internal(
-        server_address=args.server,
+        server_address=args.superlink,
         load_client_app_fn=load_fn,
-        transport="rest" if args.rest else "grpc-rere",
+        transport=args.transport,
         root_certificates=root_certificates,
         insecure=args.insecure,
         authentication_keys=authentication_keys,
@@ -85,6 +102,26 @@ def run_client_app() -> None:
     register_exit_handlers(event_type=EventType.RUN_CLIENT_APP_LEAVE)
 
 
+def _warn_deprecated_server_arg(args: argparse.Namespace) -> None:
+    """Warn about the deprecated argument `--server`."""
+    if args.server != ADDRESS_FLEET_API_GRPC_RERE:
+        warn = "Passing flag --server is deprecated. Use --superlink instead."
+        warn_deprecated_feature(warn)
+
+        if args.superlink != ADDRESS_FLEET_API_GRPC_RERE:
+            # if `--superlink` also passed, then
+            # warn user that this argument overrides what was passed with `--server`
+            log(
+                WARN,
+                "Both `--server` and `--superlink` were passed. "
+                "`--server` will be ignored. Connecting to the Superlink Fleet API "
+                "at %s.",
+                args.superlink,
+            )
+        else:
+            args.superlink = args.server
+
+
 def _get_certificates(args: argparse.Namespace) -> Optional[bytes]:
     """Load certificates if specified in args."""
     # Obtain certificates
@@ -100,7 +137,7 @@ def _get_certificates(args: argparse.Namespace) -> Optional[bytes]:
             WARN,
             "Option `--insecure` was set. "
             "Starting insecure HTTP client connected to %s.",
-            args.server,
+            args.superlink,
         )
         root_certificates = None
     else:
@@ -114,31 +151,95 @@ def _get_certificates(args: argparse.Namespace) -> Optional[bytes]:
             DEBUG,
             "Starting secure HTTPS client connected to %s "
             "with the following certificates: %s.",
-            args.server,
+            args.superlink,
             cert_path,
         )
     return root_certificates
 
 
 def _get_load_client_app_fn(
-    args: argparse.Namespace,
-) -> Callable[[], ClientApp]:
-    """Get the load_client_app_fn function."""
-    client_app_dir = args.dir
-    if client_app_dir is not None:
-        sys.path.insert(0, client_app_dir)
+    args: argparse.Namespace, multi_app: bool
+) -> Callable[[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.
+    """
+    # Find the Flower directory containing Flower Apps (only for multi-app)
+    flwr_dir = Path("")
+    if "flwr_dir" in args:
+        if args.flwr_dir is None:
+            flwr_dir = get_flwr_dir()
+        else:
+            flwr_dir = Path(args.flwr_dir).absolute()
+
+    sys.path.insert(0, str(flwr_dir.absolute()))
+
+    default_app_ref: str = getattr(args, "client-app")
+
+    if not multi_app:
+        log(
+            DEBUG,
+            "Flower SuperNode will load and validate ClientApp `%s`",
+            getattr(args, "client-app"),
+        )
+        valid, error_msg = validate(default_app_ref)
+        if not valid and error_msg:
+            raise LoadClientAppError(error_msg) from None
+
+    def _load(fab_id: str, fab_version: str) -> ClientApp:
+        # If multi-app feature is disabled
+        if not multi_app:
+            # Get sys path to be inserted
+            sys_path = Path(args.dir).absolute()
+
+            # Set app reference
+            client_app_ref = default_app_ref
+        # If multi-app feature is enabled but the fab id is not specified
+        elif fab_id == "":
+            if default_app_ref == "":
+                raise LoadClientAppError(
+                    "Invalid FAB ID: The FAB ID is empty.",
+                ) from None
+
+            log(WARN, "FAB ID is not provided; the default ClientApp will be loaded.")
+            # Get sys path to be inserted
+            sys_path = Path(args.dir).absolute()
+
+            # Set app reference
+            client_app_ref = default_app_ref
+        # If multi-app feature is enabled
+        else:
+            try:
+                project_dir = get_project_dir(fab_id, fab_version, flwr_dir)
+                config = get_project_config(project_dir)
+            except Exception as e:
+                raise LoadClientAppError("Failed to load ClientApp") from e
 
-    app_ref: str = getattr(args, "client-app")
-    valid, error_msg = validate(app_ref)
-    if not valid and error_msg:
-        raise LoadClientAppError(error_msg) from None
+            # Get sys path to be inserted
+            sys_path = Path(project_dir).absolute()
 
-    def _load() -> ClientApp:
-        client_app = load_app(app_ref, LoadClientAppError)
+            # Set app reference
+            client_app_ref = config["flower"]["components"]["clientapp"]
+
+        # Set sys.path
+        sys.path.insert(0, str(sys_path))
+
+        # Load ClientApp
+        log(
+            DEBUG,
+            "Loading ClientApp `%s`",
+            client_app_ref,
+        )
+        client_app = load_app(client_app_ref, LoadClientAppError, sys_path)
 
         if not isinstance(client_app, ClientApp):
             raise LoadClientAppError(
-                f"Attribute {app_ref} is not of type {ClientApp}",
+                f"Attribute {client_app_ref} is not of type {ClientApp}",
             ) from None
 
         return client_app
@@ -199,9 +300,27 @@ def _parse_args_common(parser: argparse.ArgumentParser) -> None:
         help="Run the client without HTTPS. By default, the client runs with "
         "HTTPS enabled. Use this flag only if you understand the risks.",
     )
-    parser.add_argument(
+    ex_group = parser.add_mutually_exclusive_group()
+    ex_group.add_argument(
+        "--grpc-rere",
+        action="store_const",
+        dest="transport",
+        const=TRANSPORT_TYPE_GRPC_RERE,
+        default=TRANSPORT_TYPE_GRPC_RERE,
+        help="Use grpc-rere as a transport layer for the client.",
+    )
+    ex_group.add_argument(
+        "--grpc-adapter",
+        action="store_const",
+        dest="transport",
+        const=TRANSPORT_TYPE_GRPC_ADAPTER,
+        help="Use grpc-adapter as a transport layer for the client.",
+    )
+    ex_group.add_argument(
         "--rest",
-        action="store_true",
+        action="store_const",
+        dest="transport",
+        const=TRANSPORT_TYPE_REST,
         help="Use REST as a transport layer for the client.",
     )
     parser.add_argument(
@@ -213,9 +332,14 @@ def _parse_args_common(parser: argparse.ArgumentParser) -> None:
     )
     parser.add_argument(
         "--server",
-        default="0.0.0.0:9092",
+        default=ADDRESS_FLEET_API_GRPC_RERE,
         help="Server address",
     )
+    parser.add_argument(
+        "--superlink",
+        default=ADDRESS_FLEET_API_GRPC_RERE,
+        help="SuperLink Fleet API (gRPC-rere) address (IPv4, IPv6, or a domain name)",
+    )
     parser.add_argument(
         "--max-retries",
         type=int,

flwr/common/__init__.py

@@ -63,43 +63,34 @@ from .typing import Status as Status
 
 __all__ = [
     "Array",
-    "array_from_numpy",
-    "bytes_to_ndarray",
     "ClientMessage",
     "Code",
     "Config",
     "ConfigsRecord",
-    "configure",
     "Context",
+    "DEFAULT_TTL",
     "DisconnectRes",
+    "Error",
     "EvaluateIns",
     "EvaluateRes",
-    "event",
     "EventType",
     "FitIns",
     "FitRes",
-    "Error",
+    "GRPC_MAX_MESSAGE_LENGTH",
     "GetParametersIns",
     "GetParametersRes",
     "GetPropertiesIns",
     "GetPropertiesRes",
-    "GRPC_MAX_MESSAGE_LENGTH",
-    "log",
     "Message",
     "MessageType",
     "MessageTypeLegacy",
-    "DEFAULT_TTL",
     "Metadata",
     "Metrics",
     "MetricsAggregationFn",
     "MetricsRecord",
-    "ndarray_to_bytes",
-    "now",
     "NDArray",
     "NDArrays",
-    "ndarrays_to_parameters",
     "Parameters",
-    "parameters_to_ndarrays",
     "ParametersRecord",
     "Properties",
     "ReconnectIns",
@@ -107,4 +98,13 @@ __all__ = [
     "Scalar",
     "ServerMessage",
     "Status",
+    "array_from_numpy",
+    "bytes_to_ndarray",
+    "configure",
+    "event",
+    "log",
+    "ndarray_to_bytes",
+    "ndarrays_to_parameters",
+    "now",
+    "parameters_to_ndarrays",
 ]

flwr/common/config.py

@@ -0,0 +1,71 @@
+# 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.
+# ==============================================================================
+"""Provide functions for managing global Flower config."""
+
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional, Union
+
+import tomli
+
+from flwr.cli.config_utils import validate_fields
+from flwr.common.constant import APP_DIR, FAB_CONFIG_FILE, FLWR_HOME
+
+
+def get_flwr_dir() -> Path:
+    """Return the Flower home directory based on env variables."""
+    return Path(
+        os.getenv(
+            FLWR_HOME,
+            f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}/.flwr",
+        )
+    )
+
+
+def get_project_dir(
+    fab_id: str, fab_version: str, flwr_dir: Optional[Union[str, Path]] = None
+) -> Path:
+    """Return the project directory based on the given fab_id and fab_version."""
+    # Check the fab_id
+    if fab_id.count("/") != 1:
+        raise ValueError(
+            f"Invalid FAB ID: {fab_id}",
+        )
+    publisher, project_name = fab_id.split("/")
+    if flwr_dir is None:
+        flwr_dir = get_flwr_dir()
+    return Path(flwr_dir) / APP_DIR / publisher / project_name / fab_version
+
+
+def get_project_config(project_dir: Union[str, Path]) -> Dict[str, Any]:
+    """Return pyproject.toml in the given project directory."""
+    # Load pyproject.toml file
+    toml_path = Path(project_dir) / FAB_CONFIG_FILE
+    if not toml_path.is_file():
+        raise FileNotFoundError(
+            f"Cannot find {FAB_CONFIG_FILE} in {project_dir}",
+        )
+    with toml_path.open(encoding="utf-8") as toml_file:
+        config = tomli.loads(toml_file.read())
+
+    # Validate pyproject.toml fields
+    is_valid, errors, _ = validate_fields(config)
+    if not is_valid:
+        error_msg = "\n".join([f"  - {error}" for error in errors])
+        raise ValueError(
+            f"Invalid {FAB_CONFIG_FILE}:\n{error_msg}",
+        )
+
+    return config

flwr/common/constant.py

@@ -27,6 +27,7 @@ To use the REST API, install `flwr` with the `rest` extra:
 
 TRANSPORT_TYPE_GRPC_BIDI = "grpc-bidi"
 TRANSPORT_TYPE_GRPC_RERE = "grpc-rere"
+TRANSPORT_TYPE_GRPC_ADAPTER = "grpc-adapter"
 TRANSPORT_TYPE_REST = "rest"
 TRANSPORT_TYPE_VCE = "vce"
 TRANSPORT_TYPES = [
@@ -36,6 +37,8 @@ TRANSPORT_TYPES = [
     TRANSPORT_TYPE_VCE,
 ]
 
+SUPEREXEC_DEFAULT_ADDRESS = "0.0.0.0:9093"
+
 # Constants for ping
 PING_DEFAULT_INTERVAL = 30
 PING_CALL_TIMEOUT = 5
@@ -43,6 +46,18 @@ PING_BASE_MULTIPLIER = 0.8
 PING_RANDOM_RANGE = (-0.1, 0.1)
 PING_MAX_INTERVAL = 1e300
 
+GRPC_ADAPTER_METADATA_FLOWER_VERSION_KEY = "flower-version"
+GRPC_ADAPTER_METADATA_SHOULD_EXIT_KEY = "should-exit"
+
+# Constants for FAB
+APP_DIR = "apps"
+FAB_CONFIG_FILE = "pyproject.toml"
+FLWR_HOME = "FLWR_HOME"
+
+
+GRPC_ADAPTER_METADATA_FLOWER_VERSION_KEY = "flower-version"
+GRPC_ADAPTER_METADATA_SHOULD_EXIT_KEY = "should-exit"
+
 
 class MessageType:
     """Message type."""