flwr-nightly 1.14.0.dev20241202__py3-none-any.whl → 1.14.0.dev20241214__py3-none-any.whl

flwr/cli/stop.py

@@ -0,0 +1,91 @@
+# 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 command line interface `stop` command."""
+
+
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+
+from flwr.cli.config_utils import (
+    exit_if_no_address,
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from flwr.common.constant import FAB_CONFIG_FILE
+from flwr.proto.exec_pb2 import StopRunRequest, StopRunResponse  # pylint: disable=E0611
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+from .utils import init_channel, try_obtain_cli_auth_plugin
+
+
+def stop(
+    run_id: Annotated[  # pylint: disable=unused-argument
+        int,
+        typer.Argument(help="The Flower run ID to stop"),
+    ],
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation"),
+    ] = None,
+) -> None:
+    """Stop a run."""
+    # Load and validate federation config
+    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+
+    pyproject_path = app / FAB_CONFIG_FILE if app else None
+    config, errors, warnings = load_and_validate(path=pyproject_path)
+    config = process_loaded_project_config(config, errors, warnings)
+    federation, federation_config = validate_federation_in_project_config(
+        federation, config
+    )
+    exit_if_no_address(federation_config, "stop")
+
+    try:
+        auth_plugin = try_obtain_cli_auth_plugin(app, federation, federation_config)
+        channel = init_channel(app, federation_config, auth_plugin)
+        stub = ExecStub(channel)  # pylint: disable=unused-variable # noqa: F841
+
+        typer.secho(f"✋ Stopping run ID {run_id}...", fg=typer.colors.GREEN)
+        _stop_run(stub, run_id=run_id)
+
+    except ValueError as err:
+        typer.secho(
+            f"❌ {err}",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1) from err
+    finally:
+        channel.close()
+
+
+def _stop_run(
+    stub: ExecStub,  # pylint: disable=unused-argument
+    run_id: int,  # pylint: disable=unused-argument
+) -> None:
+    """Stop a run."""
+    response: StopRunResponse = stub.StopRun(request=StopRunRequest(run_id=run_id))
+
+    if response.success:
+        typer.secho(f"✅ Run {run_id} successfully stopped.", fg=typer.colors.GREEN)
+    else:
+        typer.secho(f"❌ Run {run_id} couldn't be stopped.", fg=typer.colors.RED)

flwr/cli/utils.py

@@ -14,13 +14,34 @@
 # ==============================================================================
 """Flower command line interface utils."""
 
+
 import hashlib
+import json
 import re
+from logging import DEBUG
 from pathlib import Path
-from typing import Callable, Optional, cast
+from typing import Any, Callable, Optional, cast
 
+import grpc
 import typer
 
+from flwr.cli.cli_user_auth_interceptor import CliUserAuthInterceptor
+from flwr.common.address import parse_address
+from flwr.common.auth_plugin import CliAuthPlugin
+from flwr.common.constant import AUTH_TYPE, CREDENTIALS_DIR, FLWR_DIR
+from flwr.common.grpc import GRPC_MAX_MESSAGE_LENGTH, create_channel
+from flwr.common.logger import log
+
+from .config_utils import validate_certificate_in_federation_config
+
+try:
+    from flwr.ee import get_cli_auth_plugins
+except ImportError:
+
+    def get_cli_auth_plugins() -> dict[str, type[CliAuthPlugin]]:
+        """Return all CLI authentication plugins."""
+        raise NotImplementedError("No authentication plugins are currently supported.")
+
 
 def prompt_text(
     text: str,
@@ -136,3 +157,90 @@ def get_sha256_hash(file_path: Path) -> str:
                 break
             sha256.update(data)
     return sha256.hexdigest()
+
+
+def get_user_auth_config_path(
+    root_dir: Path, federation: str, server_address: str
+) -> Path:
+    """Return the path to the user auth config file."""
+    # Parse the server address
+    parsed_addr = parse_address(server_address)
+    if parsed_addr is None:
+        raise ValueError(f"Invalid server address: {server_address}")
+    host, port, is_v6 = parsed_addr
+    formatted_addr = f"[{host}]_{port}" if is_v6 else f"{host}_{port}"
+
+    # Locate the credentials directory
+    credentials_dir = root_dir.absolute() / FLWR_DIR / CREDENTIALS_DIR
+    credentials_dir.mkdir(parents=True, exist_ok=True)
+    return credentials_dir / f"{federation}_{formatted_addr}.json"
+
+
+def try_obtain_cli_auth_plugin(
+    root_dir: Path,
+    federation: str,
+    federation_config: dict[str, Any],
+    auth_type: Optional[str] = None,
+) -> Optional[CliAuthPlugin]:
+    """Load the CLI-side user auth plugin for the given auth type."""
+    config_path = get_user_auth_config_path(
+        root_dir, federation, federation_config["address"]
+    )
+
+    # Load the config file if it exists
+    config: dict[str, Any] = {}
+    if config_path.exists():
+        with config_path.open("r", encoding="utf-8") as file:
+            config = json.load(file)
+    # This is the case when the user auth is not enabled
+    elif auth_type is None:
+        return None
+
+    # Get the auth type from the config if not provided
+    if auth_type is None:
+        if AUTH_TYPE not in config:
+            return None
+        auth_type = config[AUTH_TYPE]
+
+    # Retrieve auth plugin class and instantiate it
+    try:
+        all_plugins: dict[str, type[CliAuthPlugin]] = get_cli_auth_plugins()
+        auth_plugin_class = all_plugins[auth_type]
+        return auth_plugin_class(config_path)
+    except KeyError:
+        typer.echo(f"❌ Unknown user authentication type: {auth_type}")
+        raise typer.Exit(code=1) from None
+    except ImportError:
+        typer.echo("❌ No authentication plugins are currently supported.")
+        raise typer.Exit(code=1) from None
+
+
+def init_channel(
+    app: Path, federation_config: dict[str, Any], auth_plugin: Optional[CliAuthPlugin]
+) -> grpc.Channel:
+    """Initialize gRPC channel to the Exec API."""
+
+    def on_channel_state_change(channel_connectivity: str) -> None:
+        """Log channel connectivity."""
+        log(DEBUG, channel_connectivity)
+
+    insecure, root_certificates_bytes = validate_certificate_in_federation_config(
+        app, federation_config
+    )
+
+    # Initialize the CLI-side user auth interceptor
+    interceptors: list[grpc.UnaryUnaryClientInterceptor] = []
+    if auth_plugin is not None:
+        auth_plugin.load_tokens()
+        interceptors = CliUserAuthInterceptor(auth_plugin)
+
+    # Create the gRPC channel
+    channel = create_channel(
+        server_address=federation_config["address"],
+        insecure=insecure,
+        root_certificates=root_certificates_bytes,
+        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
+        interceptors=interceptors or None,
+    )
+    channel.subscribe(on_channel_state_change)
+    return channel

flwr/client/app.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower client app."""
 
+
 import signal
 import subprocess
 import sys
@@ -474,7 +475,7 @@ def start_client_internal(
 
                     run: Run = runs[run_id]
                     if get_fab is not None and run.fab_hash:
-                        fab = get_fab(run.fab_hash)
+                        fab = get_fab(run.fab_hash, run_id)
                         if not isolation:
                             # If `ClientApp` runs in the same process, install the FAB
                             install_from_fab(fab.content, flwr_path, True)
@@ -752,7 +753,7 @@ def _init_connection(transport: Optional[str], server_address: str) -> tuple[
                 Optional[Callable[[], Optional[int]]],
                 Optional[Callable[[], None]],
                 Optional[Callable[[int], Run]],
-                Optional[Callable[[str], Fab]],
+                Optional[Callable[[str, int], Fab]],
             ]
         ],
     ],

flwr/client/client.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower client (abstract base class)."""
 
+
 # Needed to `Client` class can return a type of `Client` (not needed in py3.11+)
 from __future__ import annotations
 

flwr/client/clientapp/app.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower ClientApp process."""
 
+
 import argparse
 import sys
 import time

flwr/client/clientapp/utils.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower ClientApp loading utils."""
 
+
 from logging import DEBUG
 from pathlib import Path
 from typing import Callable, Optional

flwr/client/grpc_adapter_client/connection.py

@@ -48,7 +48,7 @@ def grpc_adapter(  # pylint: disable=R0913,too-many-positional-arguments
         Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
         Optional[Callable[[int], Run]],
-        Optional[Callable[[str], Fab]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Primitives for request/response-based interaction with a server via GrpcAdapter.

flwr/client/grpc_client/connection.py

@@ -76,7 +76,7 @@ def grpc_connection(  # pylint: disable=R0913,R0915,too-many-positional-argument
         Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
         Optional[Callable[[int], Run]],
-        Optional[Callable[[str], Fab]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Establish a gRPC connection to a gRPC server.

flwr/client/grpc_rere_client/connection.py

@@ -84,7 +84,7 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
         Optional[Callable[[int], Run]],
-        Optional[Callable[[str], Fab]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Primitives for request/response-based interaction with a server.
@@ -290,9 +290,9 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         # Return fab_id and fab_version
         return run_from_proto(get_run_response.run)
 
-    def get_fab(fab_hash: str) -> Fab:
+    def get_fab(fab_hash: str, run_id: int) -> Fab:
         # Call FleetAPI
-        get_fab_request = GetFabRequest(node=node, hash_str=fab_hash)
+        get_fab_request = GetFabRequest(node=node, hash_str=fab_hash, run_id=run_id)
         get_fab_response: GetFabResponse = retry_invoker.invoke(
             stub.GetFab,
             request=get_fab_request,

flwr/client/message_handler/message_handler.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Client-side message handler."""
 
+
 from logging import WARN
 from typing import Optional, cast
 

flwr/client/mod/comms_mods.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Mods that report statistics about message communication."""
 
+
 from logging import INFO
 
 import numpy as np

flwr/client/mod/localdp_mod.py

@@ -136,7 +136,7 @@ class LocalDpMod:
         fit_res.parameters = ndarrays_to_parameters(client_to_server_params)
 
         # Add noise to model params
-        add_localdp_gaussian_noise_to_params(
+        fit_res.parameters = add_localdp_gaussian_noise_to_params(
             fit_res.parameters, self.sensitivity, self.epsilon, self.delta
         )
 

flwr/client/nodestate/__init__.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower NodeState."""
 
+
 from .in_memory_nodestate import InMemoryNodeState as InMemoryNodeState
 from .nodestate import NodeState as NodeState
 from .nodestate_factory import NodeStateFactory as NodeStateFactory

flwr/client/nodestate/nodestate.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Abstract base class NodeState."""
 
+
 import abc
 from typing import Optional
 

flwr/client/nodestate/nodestate_factory.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Factory class that creates NodeState instances."""
 
+
 import threading
 from typing import Optional
 

flwr/client/rest_client/connection.py

@@ -96,7 +96,7 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         Optional[Callable[[], Optional[int]]],
         Optional[Callable[[], None]],
         Optional[Callable[[int], Run]],
-        Optional[Callable[[str], Fab]],
+        Optional[Callable[[str, int], Fab]],
     ]
 ]:
     """Primitives for request/response-based interaction with a server.
@@ -361,9 +361,9 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
 
         return run_from_proto(res.run)
 
-    def get_fab(fab_hash: str) -> Fab:
+    def get_fab(fab_hash: str, run_id: int) -> Fab:
         # Construct the request
-        req = GetFabRequest(node=node, hash_str=fab_hash)
+        req = GetFabRequest(node=node, hash_str=fab_hash, run_id=run_id)
 
         # Send the request
         res = _request(req, GetFabResponse, PATH_GET_FAB)

flwr/client/supernode/app.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower SuperNode."""
 
+
 import argparse
 import sys
 from logging import DEBUG, ERROR, INFO, WARN

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,6 +14,7 @@
 # ==============================================================================
 """Common Flower arguments."""
 
+
 import argparse
 import sys
 from logging import DEBUG, ERROR, WARN

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,111 @@
+# 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 Any, Optional, Union
+
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+
+class ExecAuthPlugin(ABC):
+    """Abstract Flower Auth Plugin class for ExecServicer.
+
+    Parameters
+    ----------
+    config : dict[str, Any]
+        The authentication configuration loaded from a YAML file.
+    """
+
+    @abstractmethod
+    def __init__(self, config: dict[str, Any]):
+        """Abstract constructor."""
+
+    @abstractmethod
+    def get_login_details(self) -> dict[str, str]:
+        """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, auth_details: dict[str, str]) -> dict[str, str]:
+        """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
+    ----------
+    user_auth_config_path : Path
+        The path to the user's authentication configuration file.
+    """
+
+    @staticmethod
+    @abstractmethod
+    def login(
+        login_details: dict[str, str],
+        exec_stub: ExecStub,
+    ) -> dict[str, Any]:
+        """Authenticate the user with the SuperLink.
+
+        Parameters
+        ----------
+        login_details : dict[str, str]
+            A dictionary containing the user's login details.
+        exec_stub : ExecStub
+            An instance of `ExecStub` used for communication with the SuperLink.
+
+        Returns
+        -------
+        user_auth_config : dict[str, Any]
+            A dictionary containing the user's authentication configuration
+            in JSON format.
+        """
+
+    @abstractmethod
+    def __init__(self, user_auth_config_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.
+
+        The configuration, including tokens, will be saved as a JSON file
+        at `user_auth_config_path`.
+        """
+
+    @abstractmethod
+    def load_tokens(self) -> None:
+        """Load authentication tokens from the user_auth_config_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."""

flwr/common/config.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Provide functions for managing global Flower config."""
 
+
 import os
 import re
 from pathlib import Path
@@ -27,6 +28,7 @@ from flwr.common.constant import (
     APP_DIR,
     FAB_CONFIG_FILE,
     FAB_HASH_TRUNCATION,
+    FLWR_DIR,
     FLWR_HOME,
 )
 from flwr.common.typing import Run, UserConfig, UserConfigValue
@@ -38,7 +40,7 @@ def get_flwr_dir(provided_path: Optional[str] = None) -> Path:
         return Path(
             os.getenv(
                 FLWR_HOME,
-                Path(f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}") / ".flwr",
+                Path(f"{os.getenv('XDG_DATA_HOME', os.getenv('HOME'))}") / FLWR_DIR,
             )
         )
     return Path(provided_path).absolute()

flwr/common/constant.py

@@ -80,7 +80,8 @@ FAB_ALLOWED_EXTENSIONS = {".py", ".toml", ".md"}
 FAB_CONFIG_FILE = "pyproject.toml"
 FAB_DATE = (2024, 10, 1, 0, 0, 0)
 FAB_HASH_TRUNCATION = 8
-FLWR_HOME = "FLWR_HOME"
+FLWR_DIR = ".flwr"  # The default Flower directory: ~/.flwr/
+FLWR_HOME = "FLWR_HOME"  # If set, override the default Flower directory
 
 # Constants entries in Node config for Simulation
 PARTITION_ID_KEY = "partition-id"
@@ -110,6 +111,10 @@ LOG_UPLOAD_INTERVAL = 0.2  # Minimum interval between two log uploads
 # Retry configurations
 MAX_RETRY_DELAY = 20  # Maximum delay duration between two consecutive retries.
 
+# Constants for user authentication
+CREDENTIALS_DIR = ".credentials"
+AUTH_TYPE = "auth_type"
+
 
 class MessageType:
     """Message type."""
@@ -181,3 +186,14 @@ class SubStatus:
     def __new__(cls) -> SubStatus:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class CliOutputFormat:
+    """Define output format for `flwr` CLI commands."""
+
+    DEFAULT = "default"
+    JSON = "json"
+
+    def __new__(cls) -> CliOutputFormat:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")

flwr/common/logger.py

@@ -16,9 +16,11 @@
 
 
 import logging
+import re
 import sys
 import threading
 import time
+from io import StringIO
 from logging import WARN, LogRecord
 from logging.handlers import HTTPHandler
 from queue import Empty, Queue
@@ -303,6 +305,13 @@ def restore_output() -> None:
     console_handler.stream = sys.stdout
 
 
+def redirect_output(output_buffer: StringIO) -> None:
+    """Redirect stdout and stderr to text I/O buffer."""
+    sys.stdout = output_buffer
+    sys.stderr = output_buffer
+    console_handler.stream = sys.stdout
+
+
 def _log_uploader(
     log_queue: Queue[Optional[str]], node_id: int, run_id: int, stub: ServerAppIoStub
 ) -> None:
@@ -366,3 +375,19 @@ def stop_log_uploader(
     """Stop the log uploader thread."""
     log_queue.put(None)
     log_uploader.join()
+
+
+def remove_emojis(text: str) -> str:
+    """Remove emojis from the provided text."""
+    emoji_pattern = re.compile(
+        "["
+        "\U0001F600-\U0001F64F"  # Emoticons
+        "\U0001F300-\U0001F5FF"  # Symbols & Pictographs
+        "\U0001F680-\U0001F6FF"  # Transport & Map Symbols
+        "\U0001F1E0-\U0001F1FF"  # Flags
+        "\U00002702-\U000027B0"  # Dingbats
+        "\U000024C2-\U0001F251"
+        "]+",
+        flags=re.UNICODE,
+    )
+    return emoji_pattern.sub(r"", text)

flwr/common/message.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Message."""
 
+
 from __future__ import annotations
 
 import time