flwr 1.22.0__py3-none-any.whl → 1.24.0__py3-none-any.whl

flwr/cli/supernode/__init__.py

@@ -0,0 +1,25 @@
+# Copyright 2025 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 `supernode` command."""
+
+from .ls import ls as ls
+from .register import register as register
+from .unregister import unregister as unregister
+
+__all__ = [
+    "ls",
+    "register",
+    "unregister",
+]

flwr/cli/supernode/ls.py

@@ -0,0 +1,268 @@
+# Copyright 2025 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 `supernode list` command."""
+
+
+import io
+import json
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Annotated, cast
+
+import typer
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+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, NOOP_ACCOUNT_NAME, CliOutputFormat
+from flwr.common.date import format_timedelta, isoformat8601_utc
+from flwr.common.logger import print_json_error, redirect_output, restore_output
+from flwr.proto.control_pb2 import (  # pylint: disable=E0611
+    ListNodesRequest,
+    ListNodesResponse,
+)
+from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.proto.node_pb2 import NodeInfo  # pylint: disable=E0611
+
+from ..utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+
+_NodeListType = tuple[int, str, str, str, str, str, str, str, str]
+
+
+def ls(  # pylint: disable=R0914, R0913, R0917
+    ctx: typer.Context,
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        str | None,
+        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,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable verbose output",
+        ),
+    ] = False,
+) -> None:
+    """List SuperNodes in the federation."""
+    # Resolve command used (list or ls)
+    command_name = cast(str, ctx.command.name) if ctx.command else "ls"
+
+    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 / FAB_CONFIG_FILE if app else None
+        config, errors, warnings = load_and_validate(pyproject_path, check_module=False)
+        config = process_loaded_project_config(config, errors, warnings)
+        federation, federation_config = validate_federation_in_project_config(
+            federation, config
+        )
+        exit_if_no_address(federation_config, f"supernode {command_name}")
+        channel = None
+        try:
+            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
+            channel = init_channel(app, federation_config, auth_plugin)
+            stub = ControlStub(channel)
+            typer.echo("📄 Listing all nodes...")
+            formatted_nodes = _list_nodes(stub)
+            restore_output()
+            if output_format == CliOutputFormat.JSON:
+                Console().print_json(_to_json(formatted_nodes, verbose=verbose))
+            else:
+                Console().print(_to_table(formatted_nodes, verbose=verbose))
+
+        finally:
+            if channel:
+                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 _list_nodes(stub: ControlStub) -> list[_NodeListType]:
+    """List all nodes."""
+    with flwr_cli_grpc_exc_handler():
+        res: ListNodesResponse = stub.ListNodes(ListNodesRequest())
+
+    return _format_nodes(list(res.nodes_info), res.now)
+
+
+def _format_nodes(
+    nodes_info: list[NodeInfo], now_isoformat: str
+) -> list[_NodeListType]:
+    """Format node information for display."""
+
+    def _format_datetime(dt_str: str | None) -> str:
+        dt = datetime.fromisoformat(dt_str) if dt_str else None
+        return isoformat8601_utc(dt).replace("T", " ") if dt else "N/A"
+
+    formatted_nodes: list[_NodeListType] = []
+    # Add rows
+    for node in sorted(
+        nodes_info, key=lambda x: datetime.fromisoformat(x.registered_at)
+    ):
+
+        # Calculate elapsed times
+        elapsed_time_activated = timedelta()
+        if node.last_activated_at:
+            end_time = datetime.fromisoformat(now_isoformat)
+            elapsed_time_activated = end_time - datetime.fromisoformat(
+                node.last_activated_at
+            )
+
+        formatted_nodes.append(
+            (
+                node.node_id,
+                node.owner_aid,
+                node.owner_name,
+                node.status,
+                _format_datetime(node.registered_at),
+                _format_datetime(node.last_activated_at),
+                _format_datetime(node.last_deactivated_at),
+                _format_datetime(node.unregistered_at),
+                format_timedelta(elapsed_time_activated),
+            )
+        )
+
+    return formatted_nodes
+
+
+def _to_table(nodes_info: list[_NodeListType], verbose: bool) -> Table:
+    """Format the provided node list to a rich Table."""
+    table = Table(header_style="bold cyan", show_lines=True)
+
+    # Add columns
+    table.add_column(
+        Text("Node ID", justify="center"), style="bright_black", no_wrap=True
+    )
+    table.add_column(Text("Owner", justify="center"))
+    table.add_column(Text("Status", justify="center"))
+    table.add_column(Text("Elapsed", justify="center"))
+    table.add_column(Text("Status Changed @", justify="center"), style="bright_black")
+
+    for row in nodes_info:
+        (
+            node_id,
+            _,
+            owner_name,
+            status,
+            _,
+            last_activated_at,
+            last_deactivated_at,
+            unregistered_at,
+            elapse_activated,
+        ) = row
+
+        if status == "online":
+            status_style = "green"
+            time_at = last_activated_at
+        elif status == "offline":
+            status_style = "bright_yellow"
+            time_at = last_deactivated_at
+        elif status == "unregistered":
+            if not verbose:
+                continue
+            status_style = "red"
+            time_at = unregistered_at
+        elif status == "registered":
+            status_style = "blue"
+            time_at = "N/A"
+        else:
+            raise ValueError(f"Unexpected node status '{status}'")
+
+        formatted_row = (
+            f"[bold]{node_id}[/bold]",
+            (
+                f"{owner_name}"
+                if owner_name != NOOP_ACCOUNT_NAME
+                else f"[dim]{owner_name}[/dim]"
+            ),
+            f"[{status_style}]{status}",
+            f"[cyan]{elapse_activated}[/cyan]" if status == "online" else "",
+            time_at,
+        )
+        table.add_row(*formatted_row)
+
+    return table
+
+
+def _to_json(nodes_info: list[_NodeListType], verbose: bool) -> str:
+    """Format node list to a JSON formatted string."""
+    nodes_list = []
+    for row in nodes_info:
+        (
+            node_id,
+            owner_aid,
+            owner_name,
+            status,
+            created_at,
+            activated_at,
+            deactivated_at,
+            deleted_at,
+            elapse_activated,
+        ) = row
+
+        if status == "deleted" and not verbose:
+            continue
+
+        nodes_list.append(
+            {
+                "node-id": node_id,
+                "owner-aid": owner_aid,
+                "owner-name": owner_name,
+                "status": status,
+                "created-at": created_at,
+                "online-at": activated_at,
+                "online-elapsed": elapse_activated,
+                "offline-at": deactivated_at,
+                "deleted-at": deleted_at,
+            }
+        )
+
+    return json.dumps({"success": True, "nodes": nodes_list})

flwr/cli/supernode/register.py

@@ -0,0 +1,190 @@
+# Copyright 2025 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 `supernode register` command."""
+
+
+import io
+import json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from cryptography.exceptions import UnsupportedAlgorithm
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ec
+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.exit import ExitCode, flwr_exit
+from flwr.common.logger import print_json_error, redirect_output, restore_output
+from flwr.proto.control_pb2 import (  # pylint: disable=E0611
+    RegisterNodeRequest,
+    RegisterNodeResponse,
+)
+from flwr.proto.control_pb2_grpc import ControlStub
+from flwr.supercore.primitives.asymmetric import public_key_to_bytes, uses_nist_ec_curve
+
+from ..utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+
+
+def register(  # pylint: disable=R0914
+    public_key: Annotated[
+        Path,
+        typer.Argument(
+            help="Path to a P-384 (or any other NIST EC curve) public key file.",
+        ),
+    ],
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        str | None,
+        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:
+    """Add a SuperNode to the federation."""
+    suppress_output = output_format == CliOutputFormat.JSON
+    captured_output = io.StringIO()
+
+    # Load public key
+    public_key_path = Path(public_key)
+    public_key_bytes = try_load_public_key(public_key_path)
+
+    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(pyproject_path, check_module=False)
+        config = process_loaded_project_config(config, errors, warnings)
+        federation, federation_config = validate_federation_in_project_config(
+            federation, config
+        )
+        exit_if_no_address(federation_config, "supernode register")
+
+        channel = None
+        try:
+            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
+            channel = init_channel(app, federation_config, auth_plugin)
+            stub = ControlStub(channel)  # pylint: disable=unused-variable # noqa: F841
+
+            _register_node(
+                stub=stub, public_key=public_key_bytes, output_format=output_format
+            )
+
+        except ValueError as err:
+            typer.secho(
+                f"❌ {err}",
+                fg=typer.colors.RED,
+                bold=True,
+                err=True,
+            )
+            raise typer.Exit(code=1) from err
+        finally:
+            if channel:
+                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,
+                err=True,
+            )
+    finally:
+        if suppress_output:
+            restore_output()
+        captured_output.close()
+
+
+def _register_node(stub: ControlStub, public_key: bytes, output_format: str) -> None:
+    """Register a node."""
+    with flwr_cli_grpc_exc_handler():
+        response: RegisterNodeResponse = stub.RegisterNode(
+            request=RegisterNodeRequest(public_key=public_key)
+        )
+    if response.node_id:
+        typer.secho(
+            f"✅ SuperNode {response.node_id} registered successfully.",
+            fg=typer.colors.GREEN,
+        )
+        if output_format == CliOutputFormat.JSON:
+            run_output = json.dumps(
+                {
+                    "success": True,
+                    "node-id": response.node_id,
+                }
+            )
+            restore_output()
+            Console().print_json(run_output)
+    else:
+        typer.secho(
+            "❌ SuperNode couldn't be registered.", fg=typer.colors.RED, err=True
+        )
+
+
+def try_load_public_key(public_key_path: Path) -> bytes:
+    """Try to load a public key from a file."""
+    if not public_key_path.exists():
+        typer.secho(
+            f"❌ Public key file '{public_key_path}' does not exist.",
+            fg=typer.colors.RED,
+            bold=True,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    with open(public_key_path, "rb") as key_file:
+        try:
+            public_key = serialization.load_ssh_public_key(key_file.read())
+
+            if not isinstance(public_key, ec.EllipticCurvePublicKey):
+                raise ValueError(f"Not an EC public key, got {type(public_key)}")
+
+            # Verify it's one of the approved NIST curves
+            if not uses_nist_ec_curve(public_key):
+                raise ValueError(
+                    f"EC curve {public_key.curve.name} is not an approved NIST curve"
+                )
+
+        except (ValueError, UnsupportedAlgorithm) as err:
+            flwr_exit(
+                ExitCode.FLWRCLI_NODE_AUTH_PUBLIC_KEY_INVALID,
+                str(err),
+            )
+    return public_key_to_bytes(public_key)

flwr/cli/supernode/unregister.py

@@ -0,0 +1,140 @@
+# Copyright 2025 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 `supernode unregister` command."""
+
+
+import io
+import json
+from pathlib import Path
+from typing import Annotated
+
+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.control_pb2 import UnregisterNodeRequest  # pylint: disable=E0611
+from flwr.proto.control_pb2_grpc import ControlStub
+
+from ..utils import flwr_cli_grpc_exc_handler, init_channel, load_cli_auth_plugin
+
+
+def unregister(  # pylint: disable=R0914
+    node_id: Annotated[
+        int,
+        typer.Argument(
+            help="ID of the SuperNode to remove.",
+        ),
+    ],
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project"),
+    ] = Path("."),
+    federation: Annotated[
+        str | None,
+        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:
+    """Unregister a SuperNode from the federation."""
+    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(pyproject_path, check_module=False)
+        config = process_loaded_project_config(config, errors, warnings)
+        federation, federation_config = validate_federation_in_project_config(
+            federation, config
+        )
+        exit_if_no_address(federation_config, "supernode unregister")
+
+        channel = None
+        try:
+            auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
+            channel = init_channel(app, federation_config, auth_plugin)
+            stub = ControlStub(channel)  # pylint: disable=unused-variable # noqa: F841
+
+            _unregister_node(stub=stub, node_id=node_id, output_format=output_format)
+
+        except ValueError as err:
+            typer.secho(
+                f"❌ {err}",
+                fg=typer.colors.RED,
+                bold=True,
+                err=True,
+            )
+            raise typer.Exit(code=1) from err
+        finally:
+            if channel:
+                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,
+                err=True,
+            )
+    finally:
+        if suppress_output:
+            restore_output()
+        captured_output.close()
+
+
+def _unregister_node(
+    stub: ControlStub,
+    node_id: int,
+    output_format: str,
+) -> None:
+    """Unregister a SuperNode from the federation."""
+    with flwr_cli_grpc_exc_handler():
+        stub.UnregisterNode(request=UnregisterNodeRequest(node_id=node_id))
+    typer.secho(
+        f"✅ SuperNode {node_id} unregistered successfully.", fg=typer.colors.GREEN
+    )
+    if output_format == CliOutputFormat.JSON:
+        run_output = json.dumps(
+            {
+                "success": True,
+                "node-id": node_id,
+            }
+        )
+        restore_output()
+        Console().print_json(run_output)