flwr 1.14.0__py3-none-any.whl → 1.15.0__py3-none-any.whl

flwr/client/rest_client/connection.py

@@ -16,7 +16,6 @@
 
 
 import random
-import sys
 import threading
 from collections.abc import Iterator
 from contextlib import contextmanager
@@ -26,22 +25,22 @@ from typing import Callable, Optional, TypeVar, Union
 
 from cryptography.hazmat.primitives.asymmetric import ec
 from google.protobuf.message import Message as GrpcMessage
+from requests.exceptions import ConnectionError as RequestsConnectionError
 
 from flwr.client.heartbeat import start_ping_loop
 from flwr.client.message_handler.message_handler import validate_out_message
-from flwr.client.message_handler.task_handler import get_task_ins, validate_task_ins
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.constant import (
-    MISSING_EXTRA_REST,
     PING_BASE_MULTIPLIER,
     PING_CALL_TIMEOUT,
     PING_DEFAULT_INTERVAL,
     PING_RANDOM_RANGE,
 )
+from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.logger import log
 from flwr.common.message import Message, Metadata
 from flwr.common.retry_invoker import RetryInvoker
-from flwr.common.serde import message_from_taskins, message_to_taskres, run_from_proto
+from flwr.common.serde import message_from_proto, message_to_proto, run_from_proto
 from flwr.common.typing import Fab, Run
 from flwr.proto.fab_pb2 import GetFabRequest, GetFabResponse  # pylint: disable=E0611
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
@@ -51,25 +50,26 @@ from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     DeleteNodeResponse,
     PingRequest,
     PingResponse,
-    PullTaskInsRequest,
-    PullTaskInsResponse,
-    PushTaskResRequest,
-    PushTaskResResponse,
+    PullMessagesRequest,
+    PullMessagesResponse,
+    PushMessagesRequest,
+    PushMessagesResponse,
 )
 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:
     import requests
 except ModuleNotFoundError:
-    sys.exit(MISSING_EXTRA_REST)
+    flwr_exit(ExitCode.COMMON_MISSING_EXTRA_REST)
 
 
 PATH_CREATE_NODE: str = "api/v0/fleet/create-node"
 PATH_DELETE_NODE: str = "api/v0/fleet/delete-node"
 PATH_PULL_TASK_INS: str = "api/v0/fleet/pull-task-ins"
+PATH_PULL_MESSAGES: str = "/api/v0/fleet/pull-messages"
 PATH_PUSH_TASK_RES: str = "api/v0/fleet/push-task-res"
+PATH_PUSH_MESSAGES: str = "/api/v0/fleet/push-messages"
 PATH_PING: str = "api/v0/fleet/ping"
 PATH_GET_RUN: str = "/api/v0/fleet/get-run"
 PATH_GET_FAB: str = "/api/v0/fleet/get-fab"
@@ -286,29 +286,28 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
             log(ERROR, "Node instance missing")
             return None
 
-        # Request instructions (task) from server
-        req = PullTaskInsRequest(node=node)
+        # Request instructions (message) from server
+        req = PullMessagesRequest(node=node)
 
         # Send the request
-        res = _request(req, PullTaskInsResponse, PATH_PULL_TASK_INS)
+        res = _request(req, PullMessagesResponse, PATH_PULL_MESSAGES)
         if res is None:
             return None
 
-        # Get the current TaskIns
-        task_ins: Optional[TaskIns] = get_task_ins(res)
+        # Get the current Messages
+        message_proto = None if len(res.messages_list) == 0 else res.messages_list[0]
 
-        # Discard the current TaskIns if not valid
-        if task_ins is not None and not (
-            task_ins.task.consumer.node_id == node.node_id
-            and validate_task_ins(task_ins)
+        # Discard the current message if not valid
+        if message_proto is not None and not (
+            message_proto.metadata.dst_node_id == node.node_id
         ):
-            task_ins = None
+            message_proto = None
 
         # Return the Message if available
         nonlocal metadata
         message = None
-        if task_ins is not None:
-            message = message_from_taskins(task_ins)
+        if message_proto is not None:
+            message = message_from_proto(message_proto)
             metadata = copy(message.metadata)
             log(INFO, "[Node] POST /%s: success", PATH_PULL_TASK_INS)
         return message
@@ -332,14 +331,14 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
             return
         metadata = None
 
-        # Construct TaskRes
-        task_res = message_to_taskres(message)
+        # Serialize ProtoBuf to bytes
+        message_proto = message_to_proto(message=message)
 
         # Serialize ProtoBuf to bytes
-        req = PushTaskResRequest(node=node, task_res_list=[task_res])
+        req = PushMessagesRequest(node=node, messages_list=[message_proto])
 
         # Send the request
-        res = _request(req, PushTaskResResponse, PATH_PUSH_TASK_RES)
+        res = _request(req, PushMessagesResponse, PATH_PUSH_MESSAGES)
         if res is None:
             return
 
@@ -380,3 +379,12 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         yield (receive, send, create_node, delete_node, get_run, get_fab)
     except Exception as exc:  # pylint: disable=broad-except
         log(ERROR, exc)
+    # Cleanup
+    finally:
+        try:
+            if node is not None:
+                # Disable retrying
+                retry_invoker.max_tries = 1
+                delete_node()
+        except RequestsConnectionError:
+            pass

flwr/client/supernode/app.py

@@ -16,7 +16,6 @@
 
 
 import argparse
-import sys
 from logging import DEBUG, ERROR, INFO, WARN
 from pathlib import Path
 from typing import Optional
@@ -40,8 +39,9 @@ from flwr.common.constant import (
     TRANSPORT_TYPE_GRPC_RERE,
     TRANSPORT_TYPE_REST,
 )
+from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.exit_handlers import register_exit_handlers
-from flwr.common.logger import log, warn_deprecated_feature
+from flwr.common.logger import log
 
 from ..app import start_client_internal
 from ..clientapp.utils import get_load_client_app_fn
@@ -50,7 +50,6 @@ from ..clientapp.utils import get_load_client_app_fn
 def run_supernode() -> None:
     """Run Flower SuperNode."""
     args = _parse_args_run_supernode().parse_args()
-    _warn_deprecated_server_arg(args)
 
     log(INFO, "Starting Flower SuperNode")
 
@@ -64,17 +63,6 @@ def run_supernode() -> None:
             "Ignoring `--flwr-dir`.",
         )
 
-    # Exit if unsupported argument is passed by the user
-    if args.app is not None:
-        log(
-            ERROR,
-            "The `app` argument is deprecated. The SuperNode now automatically "
-            "uses the ClientApp delivered from the SuperLink. Providing the app "
-            "directory manually is no longer supported. Please remove the `app` "
-            "argument from your command.",
-        )
-        sys.exit(1)
-
     root_certificates = try_obtain_root_certificates(args, args.superlink)
     load_fn = get_load_client_app_fn(
         default_app_ref="",
@@ -86,6 +74,12 @@ def run_supernode() -> None:
 
     log(DEBUG, "Isolation mode: %s", args.isolation)
 
+    # Register handlers for graceful shutdown
+    register_exit_handlers(
+        event_type=EventType.RUN_SUPERNODE_LEAVE,
+        exit_message="SuperNode terminated gracefully.",
+    )
+
     start_client_internal(
         server_address=args.superlink,
         load_client_app_fn=load_fn,
@@ -103,11 +97,6 @@ def run_supernode() -> None:
         clientappio_api_address=args.clientappio_api_address,
     )
 
-    # Graceful shutdown
-    register_exit_handlers(
-        event_type=EventType.RUN_SUPERNODE_LEAVE,
-    )
-
 
 def run_client_app() -> None:
     """Run Flower client app."""
@@ -119,43 +108,11 @@ 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 != FLEET_API_GRPC_RERE_DEFAULT_ADDRESS:
-        warn = "Passing flag --server is deprecated. Use --superlink instead."
-        warn_deprecated_feature(warn)
-
-        if args.superlink != FLEET_API_GRPC_RERE_DEFAULT_ADDRESS:
-            # 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 _parse_args_run_supernode() -> argparse.ArgumentParser:
     """Parse flower-supernode command line arguments."""
     parser = argparse.ArgumentParser(
         description="Start a Flower SuperNode",
     )
-
-    parser.add_argument(
-        "app",
-        nargs="?",
-        default=None,
-        help=(
-            "(REMOVED) This argument is removed. The SuperNode now automatically "
-            "uses the ClientApp delivered from the SuperLink, so there is no need to "
-            "provide the app directory manually. This argument will be removed in a "
-            "future version."
-        ),
-    )
     _parse_args_common(parser)
     parser.add_argument(
         "--flwr-dir",
@@ -228,15 +185,12 @@ def _parse_args_common(parser: argparse.ArgumentParser) -> None:
         help="Specifies the path to the PEM-encoded root certificate file for "
         "establishing secure HTTPS connections.",
     )
-    parser.add_argument(
-        "--server",
-        default=FLEET_API_GRPC_RERE_DEFAULT_ADDRESS,
-        help="Server address",
-    )
     parser.add_argument(
         "--superlink",
         default=FLEET_API_GRPC_RERE_DEFAULT_ADDRESS,
-        help="SuperLink Fleet API (gRPC-rere) address (IPv4, IPv6, or a domain name)",
+        help="SuperLink Fleet API address (IPv4, IPv6, or a domain name). If using the "
+        "REST (experimental) transport, ensure your address is in the form "
+        "`http://...` or `https://...` when TLS is enabled.",
     )
     parser.add_argument(
         "--max-retries",
@@ -280,11 +234,7 @@ def _try_setup_client_authentication(
         return None
 
     if not args.auth_supernode_private_key or not args.auth_supernode_public_key:
-        sys.exit(
-            "Authentication requires file paths to both "
-            "'--auth-supernode-private-key' and '--auth-supernode-public-key'"
-            "to be provided (providing only one of them is not sufficient)."
-        )
+        flwr_exit(ExitCode.SUPERNODE_NODE_AUTH_KEYS_REQUIRED)
 
     try:
         ssh_private_key = load_ssh_private_key(
@@ -294,11 +244,9 @@ def _try_setup_client_authentication(
         if not isinstance(ssh_private_key, ec.EllipticCurvePrivateKey):
             raise ValueError()
     except (ValueError, UnsupportedAlgorithm):
-        sys.exit(
-            "Error: Unable to parse the private key file in "
-            "'--auth-supernode-private-key'. Authentication requires elliptic "
-            "curve private and public key pair. Please ensure that the file "
-            "path points to a valid private key file and try again."
+        flwr_exit(
+            ExitCode.SUPERNODE_NODE_AUTH_KEYS_INVALID,
+            "Unable to parse the private key file.",
         )
 
     try:
@@ -308,11 +256,9 @@ def _try_setup_client_authentication(
         if not isinstance(ssh_public_key, ec.EllipticCurvePublicKey):
             raise ValueError()
     except (ValueError, UnsupportedAlgorithm):
-        sys.exit(
-            "Error: Unable to parse the public key file in "
-            "'--auth-supernode-public-key'. Authentication requires elliptic "
-            "curve private and public key pair. Please ensure that the file "
-            "path points to a valid public key file and try again."
+        flwr_exit(
+            ExitCode.SUPERNODE_NODE_AUTH_KEYS_INVALID,
+            "Unable to parse the public key file.",
         )
 
     return (

flwr/common/args.py

@@ -20,13 +20,9 @@ import sys
 from logging import DEBUG, ERROR, WARN
 from os.path import isfile
 from pathlib import Path
-from typing import Optional
+from typing import Optional, Union
 
-from flwr.common.constant import (
-    TRANSPORT_TYPE_GRPC_ADAPTER,
-    TRANSPORT_TYPE_GRPC_RERE,
-    TRANSPORT_TYPE_REST,
-)
+from flwr.common.constant import TRANSPORT_TYPE_REST
 from flwr.common.logger import log
 
 
@@ -55,9 +51,9 @@ def add_args_flwr_app_common(parser: argparse.ArgumentParser) -> None:
 def try_obtain_root_certificates(
     args: argparse.Namespace,
     grpc_server_address: str,
-) -> Optional[bytes]:
+) -> Optional[Union[bytes, str]]:
     """Validate and return the root certificates."""
-    root_cert_path = args.root_certificates
+    root_cert_path: Optional[str] = args.root_certificates
     if args.insecure:
         if root_cert_path is not None:
             sys.exit(
@@ -93,56 +89,38 @@ def try_obtain_root_certificates(
             grpc_server_address,
             root_cert_path,
         )
+    if args.transport == TRANSPORT_TYPE_REST:
+        return root_cert_path
     return root_certificates
 
 
 def try_obtain_server_certificates(
     args: argparse.Namespace,
-    transport_type: str,
 ) -> Optional[tuple[bytes, bytes, bytes]]:
     """Validate and return the CA cert, server cert, and server private key."""
     if args.insecure:
         log(WARN, "Option `--insecure` was set. Starting insecure HTTP server.")
         return None
     # Check if certificates are provided
-    if transport_type in [TRANSPORT_TYPE_GRPC_RERE, TRANSPORT_TYPE_GRPC_ADAPTER]:
-        if args.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:
-            if not isfile(args.ssl_ca_certfile):
-                sys.exit("Path argument `--ssl-ca-certfile` does not point to a file.")
-            if not isfile(args.ssl_certfile):
-                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
-            if not isfile(args.ssl_keyfile):
-                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
-            certificates = (
-                Path(args.ssl_ca_certfile).read_bytes(),  # CA certificate
-                Path(args.ssl_certfile).read_bytes(),  # server certificate
-                Path(args.ssl_keyfile).read_bytes(),  # server private key
-            )
-            return certificates
-        if args.ssl_certfile or args.ssl_keyfile or args.ssl_ca_certfile:
-            sys.exit(
-                "You need to provide valid file paths to `--ssl-certfile`, "
-                "`--ssl-keyfile`, and `—-ssl-ca-certfile` to create a secure "
-                "connection in Fleet API server (gRPC-rere)."
-            )
-    if transport_type == TRANSPORT_TYPE_REST:
-        if args.ssl_certfile and args.ssl_keyfile:
-            if not isfile(args.ssl_certfile):
-                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
-            if not isfile(args.ssl_keyfile):
-                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
-            certificates = (
-                b"",
-                Path(args.ssl_certfile).read_bytes(),  # server certificate
-                Path(args.ssl_keyfile).read_bytes(),  # server private key
-            )
-            return certificates
-        if args.ssl_certfile or args.ssl_keyfile:
-            sys.exit(
-                "You need to provide valid file paths to `--ssl-certfile` "
-                "and `--ssl-keyfile` to create a secure connection "
-                "in Fleet API server (REST, experimental)."
-            )
+    if args.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:
+        if not isfile(args.ssl_ca_certfile):
+            sys.exit("Path argument `--ssl-ca-certfile` does not point to a file.")
+        if not isfile(args.ssl_certfile):
+            sys.exit("Path argument `--ssl-certfile` does not point to a file.")
+        if not isfile(args.ssl_keyfile):
+            sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
+        certificates = (
+            Path(args.ssl_ca_certfile).read_bytes(),  # CA certificate
+            Path(args.ssl_certfile).read_bytes(),  # server certificate
+            Path(args.ssl_keyfile).read_bytes(),  # server private key
+        )
+        return certificates
+    if args.ssl_certfile or args.ssl_keyfile or args.ssl_ca_certfile:
+        sys.exit(
+            "You need to provide valid file paths to `--ssl-certfile`, "
+            "`--ssl-keyfile`, and `—-ssl-ca-certfile` to create a secure "
+            "connection in Fleet API server (gRPC-rere)."
+        )
     log(
         ERROR,
         "Certificates are required unless running in insecure mode. "

flwr/common/auth_plugin/auth_plugin.py

@@ -18,26 +18,32 @@
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Optional, Union
 
 from flwr.proto.exec_pb2_grpc import ExecStub
 
+from ..typing import UserAuthCredentials, UserAuthLoginDetails
+
 
 class ExecAuthPlugin(ABC):
     """Abstract Flower Auth Plugin class for ExecServicer.
 
     Parameters
     ----------
-    config : dict[str, Any]
-        The authentication configuration loaded from a YAML file.
+    user_auth_config_path : Path
+        Path to the YAML file containing the authentication configuration.
     """
 
     @abstractmethod
-    def __init__(self, config: dict[str, Any]):
+    def __init__(
+        self,
+        user_auth_config_path: Path,
+        verify_tls_cert: bool,
+    ):
         """Abstract constructor."""
 
     @abstractmethod
-    def get_login_details(self) -> dict[str, str]:
+    def get_login_details(self) -> Optional[UserAuthLoginDetails]:
         """Get the login details."""
 
     @abstractmethod
@@ -47,7 +53,7 @@ class ExecAuthPlugin(ABC):
         """Validate authentication tokens in the provided metadata."""
 
     @abstractmethod
-    def get_auth_tokens(self, auth_details: dict[str, str]) -> dict[str, str]:
+    def get_auth_tokens(self, device_code: str) -> Optional[UserAuthCredentials]:
         """Get authentication tokens."""
 
     @abstractmethod
@@ -62,50 +68,55 @@ class CliAuthPlugin(ABC):
 
     Parameters
     ----------
-    user_auth_config_path : Path
-        The path to the user's authentication configuration file.
+    credentials_path : Path
+        Path to the user's authentication credentials file.
     """
 
     @staticmethod
     @abstractmethod
     def login(
-        login_details: dict[str, str],
+        login_details: UserAuthLoginDetails,
         exec_stub: ExecStub,
-    ) -> dict[str, Any]:
-        """Authenticate the user with the SuperLink.
+    ) -> UserAuthCredentials:
+        """Authenticate the user and retrieve authentication credentials.
 
         Parameters
         ----------
-        login_details : dict[str, str]
-            A dictionary containing the user's login details.
+        login_details : UserAuthLoginDetails
+            An object containing the user's login details.
         exec_stub : ExecStub
-            An instance of `ExecStub` used for communication with the SuperLink.
+            A stub for executing RPC calls to the server.
 
         Returns
         -------
-        user_auth_config : dict[str, Any]
-            A dictionary containing the user's authentication configuration
-            in JSON format.
+        UserAuthCredentials
+            The authentication credentials obtained after login.
         """
 
     @abstractmethod
-    def __init__(self, user_auth_config_path: Path):
+    def __init__(self, credentials_path: Path):
         """Abstract constructor."""
 
     @abstractmethod
-    def store_tokens(self, user_auth_config: dict[str, Any]) -> None:
-        """Store authentication tokens from the provided user_auth_config.
+    def store_tokens(self, credentials: UserAuthCredentials) -> None:
+        """Store authentication tokens to the `credentials_path`.
 
-        The configuration, including tokens, will be saved as a JSON file
-        at `user_auth_config_path`.
+        The credentials, including tokens, will be saved as a JSON file
+        at `credentials_path`.
         """
 
     @abstractmethod
     def load_tokens(self) -> None:
-        """Load authentication tokens from the user_auth_config_path."""
+        """Load authentication tokens from the `credentials_path`."""
 
     @abstractmethod
     def write_tokens_to_metadata(
         self, metadata: Sequence[tuple[str, Union[str, bytes]]]
     ) -> Sequence[tuple[str, Union[str, bytes]]]:
         """Write authentication tokens to the provided metadata."""
+
+    @abstractmethod
+    def read_tokens_from_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Optional[UserAuthCredentials]:
+        """Read authentication tokens from the provided metadata."""