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

flwr/cli/run/run.py

@@ -14,28 +14,30 @@
 # ==============================================================================
 """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
 
 import typer
+from rich.console import Console
 
 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,
     parse_config_args,
     user_config_to_configsrecord,
 )
-from flwr.common.grpc import GRPC_MAX_MESSAGE_LENGTH, create_channel
-from flwr.common.logger import log
+from flwr.common.constant import CliOutputFormat
+from flwr.common.logger import print_json_error, redirect_output, restore_output
 from flwr.common.serde import (
     configs_record_to_proto,
     fab_to_proto,
@@ -46,15 +48,15 @@ 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,
+    unauthenticated_exc_handler,
+)
 
 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[
@@ -85,46 +87,74 @@ def run(
             "logs are not streamed by default.",
         ),
     ] = False,
+    output_format: Annotated[
+        str,
+        typer.Option(
+            "--format",
+            case_sensitive=False,
+            help="Format output using 'default' view or 'json'",
+        ),
+    ] = CliOutputFormat.DEFAULT,
 ) -> None:
     """Run Flower App."""
-    typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
-
-    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)
-    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)
-    else:
-        _run_without_exec_api(app, federation_config, config_overrides, federation)
-
+    suppress_output = output_format == CliOutputFormat.JSON
+    captured_output = io.StringIO()
+    try:
+        if suppress_output:
+            redirect_output(captured_output)
+        typer.secho("Loading project configuration... ", fg=typer.colors.BLUE)
+
+        pyproject_path = app / "pyproject.toml" 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
+        )
 
-# pylint: disable-next=too-many-locals
+        if "address" in federation_config:
+            _run_with_exec_api(
+                app,
+                federation,
+                federation_config,
+                config_overrides,
+                stream,
+                output_format,
+            )
+        else:
+            _run_without_exec_api(app, federation_config, config_overrides, federation)
+    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()
+
+
+# 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)
     content = Path(fab_path).read_bytes()
+    fab_id, fab_version = get_fab_metadata(Path(fab_path))
 
     # Delete FAB file once the bytes is computed
     Path(fab_path).unlink()
@@ -140,9 +170,29 @@ def _run_with_exec_api(
         override_config=user_config_to_proto(parse_config_args(config_overrides)),
         federation_options=configs_record_to_proto(c_record),
     )
-    res = stub.StartRun(req)
+    with unauthenticated_exc_handler():
+        res = stub.StartRun(req)
 
-    typer.secho(f"🎊 Successfully started run {res.run_id}", fg=typer.colors.GREEN)
+    if res.HasField("run_id"):
+        typer.secho(f"🎊 Successfully started run {res.run_id}", fg=typer.colors.GREEN)
+    else:
+        typer.secho("❌ Failed to start run", fg=typer.colors.RED)
+        raise typer.Exit(code=1)
+
+    if output_format == CliOutputFormat.JSON:
+        run_output = json.dumps(
+            {
+                "success": res.HasField("run_id"),
+                "run-id": res.run_id if res.HasField("run_id") else None,
+                "fab-id": fab_id,
+                "fab-name": fab_id.rsplit("/", maxsplit=1)[-1],
+                "fab-version": fab_version,
+                "fab-hash": fab_hash[:8],
+                "fab-filename": fab_path,
+            }
+        )
+        restore_output()
+        Console().print_json(run_output)
 
     if stream:
         start_stream(res.run_id, channel, CONN_REFRESH_PERIOD)

flwr/cli/stop.py

@@ -0,0 +1,130 @@
+# 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, unauthenticated_exc_handler
+
+
+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."""
+    with unauthenticated_exc_handler():
+        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,35 @@
 # ==============================================================================
 """Flower command line interface utils."""
 
+
 import hashlib
+import json
 import re
+from collections.abc import Iterator
+from contextlib import contextmanager
+from logging import DEBUG
 from pathlib import Path
-from typing import Callable, Optional, cast
+from typing import Any, Callable, Optional, Union, 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,
@@ -126,13 +148,155 @@ def sanitize_project_name(name: str) -> str:
     return sanitized_name
 
 
-def get_sha256_hash(file_path: Path) -> str:
+def get_sha256_hash(file_path_or_int: Union[Path, int]) -> str:
     """Calculate the SHA-256 hash of a file."""
     sha256 = hashlib.sha256()
-    with open(file_path, "rb") as f:
-        while True:
-            data = f.read(65536)  # Read in 64kB blocks
-            if not data:
-                break
-            sha256.update(data)
+    if isinstance(file_path_or_int, Path):
+        with open(file_path_or_int, "rb") as f:
+            while True:
+                data = f.read(65536)  # Read in 64kB blocks
+                if not data:
+                    break
+                sha256.update(data)
+    elif isinstance(file_path_or_int, int):
+        sha256.update(str(file_path_or_int).encode())
     return sha256.hexdigest()
+
+
+def get_user_auth_config_path(root_dir: Path, federation: str) -> Path:
+    """Return the path to the user auth config file.
+
+    Additionally, a `.gitignore` file will be created in the Flower directory to
+    include the `.credentials` folder to be excluded from git. If the `.gitignore`
+    file already exists, a warning will be displayed if the `.credentials` entry is
+    not found.
+    """
+    # Locate the credentials directory
+    abs_flwr_dir = root_dir.absolute() / FLWR_DIR
+    credentials_dir = abs_flwr_dir / CREDENTIALS_DIR
+    credentials_dir.mkdir(parents=True, exist_ok=True)
+
+    # Determine the absolute path of the Flower directory for .gitignore
+    gitignore_path = abs_flwr_dir / ".gitignore"
+    credential_entry = CREDENTIALS_DIR
+
+    try:
+        if gitignore_path.exists():
+            with open(gitignore_path, encoding="utf-8") as gitignore_file:
+                lines = gitignore_file.read().splitlines()
+
+            # Warn if .credentials is not already in .gitignore
+            if credential_entry not in lines:
+                typer.secho(
+                    f"`.gitignore` exists, but `{credential_entry}` entry not found. "
+                    "Consider adding it to your `.gitignore` to exclude Flower "
+                    "credentials from git.",
+                    fg=typer.colors.YELLOW,
+                    bold=True,
+                )
+        else:
+            typer.secho(
+                f"Creating a new `.gitignore` with `{credential_entry}` entry...",
+                fg=typer.colors.BLUE,
+            )
+            # Create a new .gitignore with .credentials
+            with open(gitignore_path, "w", encoding="utf-8") as gitignore_file:
+                gitignore_file.write(f"{credential_entry}\n")
+    except Exception as err:
+        typer.secho(
+            "❌ An error occurred while handling `.gitignore.` "
+            f"Please check the permissions of `{gitignore_path}` and try again.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1) from err
+
+    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
+
+
+@contextmanager
+def unauthenticated_exc_handler() -> Iterator[None]:
+    """Context manager to handle gRPC UNAUTHENTICATED errors.
+
+    It catches grpc.RpcError exceptions with UNAUTHENTICATED status, informs the user,
+    and exits the application. All other exceptions will be allowed to escape.
+    """
+    try:
+        yield
+    except grpc.RpcError as e:
+        if e.code() != grpc.StatusCode.UNAUTHENTICATED:
+            raise
+        typer.secho(
+            "❌ Authentication failed. Please run `flwr login`"
+            " to authenticate and try again.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1) from None

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
 
@@ -21,7 +22,6 @@ from abc import ABC
 
 from flwr.common import (
     Code,
-    Context,
     EvaluateIns,
     EvaluateRes,
     FitIns,
@@ -33,14 +33,11 @@ from flwr.common import (
     Parameters,
     Status,
 )
-from flwr.common.logger import warn_deprecated_feature_with_example
 
 
 class Client(ABC):
     """Abstract base class for Flower clients."""
 
-    _context: Context
-
     def get_properties(self, ins: GetPropertiesIns) -> GetPropertiesRes:
         """Return set of client's properties.
 
@@ -142,34 +139,6 @@ class Client(ABC):
             metrics={},
         )
 
-    @property
-    def context(self) -> Context:
-        """Getter for `Context` client attribute."""
-        warn_deprecated_feature_with_example(
-            "Accessing the context via the client's attribute is deprecated.",
-            example_message="Instead, pass it to the client's "
-            "constructor in your `client_fn()` which already "
-            "receives a context object.",
-            code_example="def client_fn(context: Context) -> Client:\n\n"
-            "\t\t# Your existing client_fn\n\n"
-            "\t\t# Pass `context` to the constructor\n"
-            "\t\treturn FlowerClient(context).to_client()",
-        )
-        return self._context
-
-    @context.setter
-    def context(self, context: Context) -> None:
-        """Setter for `Context` client attribute."""
-        self._context = context
-
-    def get_context(self) -> Context:
-        """Get the run context from this client."""
-        return self.context
-
-    def set_context(self, context: Context) -> None:
-        """Apply a run context to this client."""
-        self.context = context
-
     def to_client(self) -> Client:
         """Return client (itself)."""
         return self

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
 
@@ -252,12 +255,5 @@ def _parse_args_run_flwr_clientapp() -> argparse.ArgumentParser:
         required=False,
         help="Unique token generated by SuperNode for each ClientApp execution",
     )
-    parser.add_argument(
-        "--root-certificates",
-        metavar="ROOT_CERT",
-        type=str,
-        help="Specifies the path to the PEM-encoded root certificate file for "
-        "establishing secure HTTPS connections.",
-    )
     add_args_flwr_app_common(parser=parser)
     return parser

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