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

flwr/client/supernode/app.py

@@ -14,8 +14,8 @@
 # ==============================================================================
 """Flower SuperNode."""
 
+
 import argparse
-import sys
 from logging import DEBUG, ERROR, INFO, WARN
 from pathlib import Path
 from typing import Optional
@@ -39,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
@@ -49,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")
 
@@ -63,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="",
@@ -85,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,
@@ -102,60 +97,22 @@ 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."""
     event(EventType.RUN_CLIENT_APP_ENTER)
     log(
         ERROR,
-        "The command `flower-client-app` has been replaced by `flower-supernode`.",
+        "The command `flower-client-app` has been replaced by `flwr run`.",
     )
-    log(INFO, "Execute `flower-supernode --help` to learn how to use it.")
     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/address.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower IP address utils."""
 
+
 import socket
 from ipaddress import ip_address
 from typing import Optional

flwr/common/args.py

@@ -14,18 +14,15 @@
 # ==============================================================================
 """Common Flower arguments."""
 
+
 import argparse
 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
 
 
@@ -54,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(
@@ -92,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/__init__.py

@@ -0,0 +1,24 @@
+# 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.
+# ==============================================================================
+"""Auth plugin components."""
+
+
+from .auth_plugin import CliAuthPlugin as CliAuthPlugin
+from .auth_plugin import ExecAuthPlugin as ExecAuthPlugin
+
+__all__ = [
+    "CliAuthPlugin",
+    "ExecAuthPlugin",
+]

flwr/common/auth_plugin/auth_plugin.py

@@ -0,0 +1,122 @@
+# 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.
+# ==============================================================================
+"""Abstract classes for Flower User Auth Plugin."""
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from pathlib import Path
+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
+    ----------
+    user_auth_config_path : Path
+        Path to the YAML file containing the authentication configuration.
+    """
+
+    @abstractmethod
+    def __init__(
+        self,
+        user_auth_config_path: Path,
+        verify_tls_cert: bool,
+    ):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def get_login_details(self) -> Optional[UserAuthLoginDetails]:
+        """Get the login details."""
+
+    @abstractmethod
+    def validate_tokens_in_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> bool:
+        """Validate authentication tokens in the provided metadata."""
+
+    @abstractmethod
+    def get_auth_tokens(self, device_code: str) -> Optional[UserAuthCredentials]:
+        """Get authentication tokens."""
+
+    @abstractmethod
+    def refresh_tokens(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Optional[Sequence[tuple[str, Union[str, bytes]]]]:
+        """Refresh authentication tokens in the provided metadata."""
+
+
+class CliAuthPlugin(ABC):
+    """Abstract Flower Auth Plugin class for CLI.
+
+    Parameters
+    ----------
+    credentials_path : Path
+        Path to the user's authentication credentials file.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def login(
+        login_details: UserAuthLoginDetails,
+        exec_stub: ExecStub,
+    ) -> UserAuthCredentials:
+        """Authenticate the user and retrieve authentication credentials.
+
+        Parameters
+        ----------
+        login_details : UserAuthLoginDetails
+            An object containing the user's login details.
+        exec_stub : ExecStub
+            A stub for executing RPC calls to the server.
+
+        Returns
+        -------
+        UserAuthCredentials
+            The authentication credentials obtained after login.
+        """
+
+    @abstractmethod
+    def __init__(self, credentials_path: Path):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def store_tokens(self, credentials: UserAuthCredentials) -> None:
+        """Store authentication tokens to the `credentials_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 `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."""