flwr-nightly 1.14.0.dev20241204__py3-none-any.whl → 1.14.0.dev20241216__py3-none-any.whl

flwr/cli/run/run.py

@@ -14,12 +14,12 @@
 # ==============================================================================
 """Flower command line interface `run` command."""
 
+
 import io
 import json
 import subprocess
-from logging import DEBUG
 from pathlib import Path
-from typing import Annotated, Any, Optional, Union
+from typing import Annotated, Any, Optional
 
 import typer
 from rich.console import Console
@@ -28,9 +28,8 @@ from flwr.cli.build import build
 from flwr.cli.config_utils import (
     get_fab_metadata,
     load_and_validate,
-    validate_certificate_in_federation_config,
+    process_loaded_project_config,
     validate_federation_in_project_config,
-    validate_project_config,
 )
 from flwr.common.config import (
     flatten_dict,
@@ -38,8 +37,7 @@ from flwr.common.config import (
     user_config_to_configsrecord,
 )
 from flwr.common.constant import CliOutputFormat
-from flwr.common.grpc import GRPC_MAX_MESSAGE_LENGTH, create_channel
-from flwr.common.logger import log, redirect_output, remove_emojis, restore_output
+from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import (
     configs_record_to_proto,
     fab_to_proto,
@@ -50,15 +48,11 @@ from flwr.proto.exec_pb2 import StartRunRequest  # pylint: disable=E0611
 from flwr.proto.exec_pb2_grpc import ExecStub
 
 from ..log import start_stream
+from ..utils import init_channel, try_obtain_cli_auth_plugin
 
 CONN_REFRESH_PERIOD = 60  # Connection refresh period for log streaming (seconds)
 
 
-def on_channel_state_change(channel_connectivity: str) -> None:
-    """Log channel connectivity."""
-    log(DEBUG, channel_connectivity)
-
-
 # pylint: disable-next=too-many-locals
 def run(
     app: Annotated[
@@ -108,14 +102,19 @@ def run(
 
         pyproject_path = app / "pyproject.toml" if app else None
         config, errors, warnings = load_and_validate(path=pyproject_path)
-        config = validate_project_config(config, errors, warnings)
+        config = process_loaded_project_config(config, errors, warnings)
         federation, federation_config = validate_federation_in_project_config(
             federation, config
         )
 
         if "address" in federation_config:
             _run_with_exec_api(
-                app, federation_config, config_overrides, stream, output_format
+                app,
+                federation,
+                federation_config,
+                config_overrides,
+                stream,
+                output_format,
             )
         else:
             _run_without_exec_api(app, federation_config, config_overrides, federation)
@@ -123,7 +122,7 @@ def run(
         if suppress_output:
             restore_output()
             e_message = captured_output.getvalue()
-            _print_json_error(e_message, err)
+            print_json_error(e_message, err)
         else:
             typer.secho(
                 f"{err}",
@@ -136,26 +135,17 @@ def run(
         captured_output.close()
 
 
-# pylint: disable-next=too-many-locals
+# pylint: disable-next=R0913, R0914, R0917
 def _run_with_exec_api(
     app: Path,
+    federation: str,
     federation_config: dict[str, Any],
     config_overrides: Optional[list[str]],
     stream: bool,
     output_format: str,
 ) -> None:
-
-    insecure, root_certificates_bytes = validate_certificate_in_federation_config(
-        app, federation_config
-    )
-    channel = create_channel(
-        server_address=federation_config["address"],
-        insecure=insecure,
-        root_certificates=root_certificates_bytes,
-        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
-        interceptors=None,
-    )
-    channel.subscribe(on_channel_state_change)
+    auth_plugin = try_obtain_cli_auth_plugin(app, federation)
+    channel = init_channel(app, federation_config, auth_plugin)
     stub = ExecStub(channel)
 
     fab_path, fab_hash = build(app)
@@ -249,15 +239,3 @@ def _run_without_exec_api(
         check=True,
         text=True,
     )
-
-
-def _print_json_error(msg: str, e: Union[typer.Exit, Exception]) -> None:
-    """Print error message as JSON."""
-    Console().print_json(
-        json.dumps(
-            {
-                "success": False,
-                "error-message": remove_emojis(str(msg) + "\n" + str(e)),
-            }
-        )
-    )

flwr/cli/stop.py

@@ -0,0 +1,129 @@
+# 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."""
+
+
+import io
+import json
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+
+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, CliOutputFormat
+from flwr.common.logger import print_json_error, redirect_output, restore_output
+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(  # pylint: disable=R0914
+    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,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
+) -> None:
+    """Stop a run."""
+    suppress_output = output_format == CliOutputFormat.JSON
+    captured_output = io.StringIO()
+    try:
+        if suppress_output:
+            redirect_output(captured_output)
+
+        # 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)
+            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=stub, run_id=run_id, output_format=output_format)
+
+        except ValueError as err:
+            typer.secho(
+                f"❌ {err}",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1) from err
+        finally:
+            channel.close()
+    except (typer.Exit, Exception) as err:  # pylint: disable=broad-except
+        if suppress_output:
+            restore_output()
+            e_message = captured_output.getvalue()
+            print_json_error(e_message, err)
+        else:
+            typer.secho(
+                f"{err}",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+    finally:
+        if suppress_output:
+            restore_output()
+        captured_output.close()
+
+
+def _stop_run(stub: ExecStub, run_id: int, output_format: str) -> 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)
+        if output_format == CliOutputFormat.JSON:
+            run_output = json.dumps(
+                {
+                    "success": True,
+                    "run-id": run_id,
+                }
+            )
+            restore_output()
+            Console().print_json(run_output)
+    else:
+        typer.secho(f"❌ Run {run_id} couldn't be stopped.", fg=typer.colors.RED)

flwr/cli/utils.py

@@ -14,13 +14,33 @@
 # ==============================================================================
 """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.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 +156,78 @@ 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) -> Path:
+    """Return the path to the user auth config file."""
+    # 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}.json"
+
+
+def try_obtain_cli_auth_plugin(
+    root_dir: Path,
+    federation: str,
+    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)
+
+    # 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
@@ -55,7 +56,7 @@ from flwr.common.constant import (
 from flwr.common.logger import log, warn_deprecated_feature
 from flwr.common.message import Error
 from flwr.common.retry_invoker import RetryInvoker, RetryState, exponential
-from flwr.common.typing import Fab, Run, UserConfig
+from flwr.common.typing import Fab, Run, RunNotRunningException, UserConfig
 from flwr.proto.clientappio_pb2_grpc import add_ClientAppIoServicer_to_server
 from flwr.server.superlink.fleet.grpc_bidi.grpc_server import generic_create_grpc_server
 from flwr.server.superlink.linkstate.utils import generate_rand_int_from_bytes
@@ -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)
@@ -611,6 +612,16 @@ def start_client_internal(
                     send(reply_message)
                     log(INFO, "Sent reply")
 
+                except RunNotRunningException:
+                    log(INFO, "")
+                    log(
+                        INFO,
+                        "SuperNode aborted sending the reply message. "
+                        "Run ID %s is not in `RUNNING` status.",
+                        run_id,
+                    )
+                    log(INFO, "")
+
                 except StopIteration:
                     sleep_duration = 0
                     break
@@ -752,7 +763,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
@@ -31,6 +32,7 @@ from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS, ErrorCo
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
 from flwr.common.message import Error
+from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
 from flwr.common.serde import (
     context_from_proto,
     context_to_proto,
@@ -105,9 +107,9 @@ def run_clientapp(  # pylint: disable=R0914
 
     # Resolve directory where FABs are installed
     flwr_dir_ = get_flwr_dir(flwr_dir)
-
     try:
         stub = ClientAppIoStub(channel)
+        _wrap_stub(stub, _make_simple_grpc_retry_invoker())
 
         while True:
             # If token is not set, loop until token is received from SuperNode
@@ -138,6 +140,7 @@ def run_clientapp(  # pylint: disable=R0914
 
                 # Execute ClientApp
                 reply_message = client_app(message=message, context=context)
+
             except Exception as ex:  # pylint: disable=broad-exception-caught
                 # Don't update/change NodeState
 

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

@@ -42,7 +42,7 @@ 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.typing import Fab, Run
+from flwr.common.typing import Fab, Run, RunNotRunningException
 from flwr.proto.fab_pb2 import GetFabRequest, GetFabResponse  # pylint: disable=E0611
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
     CreateNodeRequest,
@@ -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.
@@ -155,10 +155,16 @@ def grpc_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     ping_thread: Optional[threading.Thread] = None
     ping_stop_event = threading.Event()
 
+    def _should_giveup_fn(e: Exception) -> bool:
+        if e.code() == grpc.StatusCode.PERMISSION_DENIED:  # type: ignore
+            raise RunNotRunningException
+        if e.code() == grpc.StatusCode.UNAVAILABLE:  # type: ignore
+            return False
+        return True
+
     # Restrict retries to cases where the status code is UNAVAILABLE
-    retry_invoker.should_giveup = (
-        lambda e: e.code() != grpc.StatusCode.UNAVAILABLE  # type: ignore
-    )
+    # If the status code is PERMISSION_DENIED, additionally raise RunNotRunningException
+    retry_invoker.should_giveup = _should_giveup_fn
 
     ###########################################################################
     # ping/create_node/delete_node/receive/send/get_run functions
@@ -290,9 +296,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",
+]