flwr-nightly 1.8.0.dev20240315__py3-none-any.whl → 1.15.0.dev20250114__py3-none-any.whl

flwr/cli/install.py

@@ -0,0 +1,253 @@
+# 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 `install` command."""
+
+
+import hashlib
+import shutil
+import tempfile
+import zipfile
+from io import BytesIO
+from pathlib import Path
+from typing import IO, Annotated, Optional, Union
+
+import typer
+
+from flwr.common.config import get_flwr_dir, get_metadata_from_config
+from flwr.common.constant import FAB_HASH_TRUNCATION
+
+from .config_utils import load_and_validate
+from .utils import get_sha256_hash
+
+
+def install(
+    source: Annotated[
+        Optional[Path],
+        typer.Argument(metavar="source", help="The source FAB file to install."),
+    ] = None,
+    flwr_dir: Annotated[
+        Optional[Path],
+        typer.Option(help="The desired install path."),
+    ] = None,
+) -> None:
+    """Install a Flower App Bundle.
+
+    It can be ran with a single FAB file argument:
+
+        ``flwr install ./target_project.fab``
+
+    The target install directory can be specified with ``--flwr-dir``:
+
+        ``flwr install ./target_project.fab --flwr-dir ./docs/flwr``
+
+    This will install ``target_project`` to ``./docs/flwr/``. By default,
+    ``flwr-dir`` is equal to:
+
+        - ``$FLWR_HOME/`` if ``$FLWR_HOME`` is defined
+        - ``$XDG_DATA_HOME/.flwr/`` if ``$XDG_DATA_HOME`` is defined
+        - ``$HOME/.flwr/`` in all other cases
+    """
+    if source is None:
+        source = Path(typer.prompt("Enter the source FAB file"))
+
+    source = source.resolve()
+    if not source.exists() or not source.is_file():
+        typer.secho(
+            f"❌ The source {source} does not exist or is not a file.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    if source.suffix != ".fab":
+        typer.secho(
+            f"❌ The source {source} is not a `.fab` file.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    install_from_fab(source, flwr_dir)
+
+
+def install_from_fab(
+    fab_file: Union[Path, bytes],
+    flwr_dir: Optional[Path],
+    skip_prompt: bool = False,
+) -> Path:
+    """Install from a FAB file after extracting and validating."""
+    fab_file_archive: Union[Path, IO[bytes]]
+    fab_name: Optional[str]
+    if isinstance(fab_file, bytes):
+        fab_file_archive = BytesIO(fab_file)
+        fab_hash = hashlib.sha256(fab_file).hexdigest()
+        fab_name = None
+    elif isinstance(fab_file, Path):
+        fab_file_archive = fab_file
+        fab_hash = hashlib.sha256(fab_file.read_bytes()).hexdigest()
+        fab_name = fab_file.stem
+    else:
+        raise ValueError("fab_file must be either a Path or bytes")
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        with zipfile.ZipFile(fab_file_archive, "r") as zipf:
+            zipf.extractall(tmpdir)
+            tmpdir_path = Path(tmpdir)
+            info_dir = tmpdir_path / ".info"
+            if not info_dir.exists():
+                typer.secho(
+                    "❌ FAB file has incorrect format.",
+                    fg=typer.colors.RED,
+                    bold=True,
+                )
+                raise typer.Exit(code=1)
+
+            content_file = info_dir / "CONTENT"
+
+            if not content_file.exists() or not _verify_hashes(
+                content_file.read_text(), tmpdir_path
+            ):
+                typer.secho(
+                    "❌ File hashes couldn't be verified.",
+                    fg=typer.colors.RED,
+                    bold=True,
+                )
+                raise typer.Exit(code=1)
+
+            shutil.rmtree(info_dir)
+
+            installed_path = validate_and_install(
+                tmpdir_path, fab_hash, fab_name, flwr_dir, skip_prompt
+            )
+
+    return installed_path
+
+
+# pylint: disable=too-many-locals
+def validate_and_install(
+    project_dir: Path,
+    fab_hash: str,
+    fab_name: Optional[str],
+    flwr_dir: Optional[Path],
+    skip_prompt: bool = False,
+) -> Path:
+    """Validate TOML files and install the project to the desired directory."""
+    config, _, _ = load_and_validate(project_dir / "pyproject.toml", check_module=False)
+
+    if config is None:
+        typer.secho(
+            "❌ Invalid config inside FAB file.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    version, fab_id = get_metadata_from_config(config)
+    publisher, project_name = fab_id.split("/")
+    config_metadata = (publisher, project_name, version, fab_hash)
+
+    if fab_name:
+        _validate_fab_and_config_metadata(fab_name, config_metadata)
+
+    install_dir: Path = (
+        (get_flwr_dir() if not flwr_dir else flwr_dir)
+        / "apps"
+        / f"{publisher}.{project_name}.{version}.{fab_hash[:FAB_HASH_TRUNCATION]}"
+    )
+    if install_dir.exists():
+        if skip_prompt:
+            return install_dir
+        if not typer.confirm(
+            typer.style(
+                f"\n💬 {project_name} version {version} is already installed, "
+                "do you want to reinstall it?",
+                fg=typer.colors.MAGENTA,
+                bold=True,
+            )
+        ):
+            return install_dir
+
+    install_dir.mkdir(parents=True, exist_ok=True)
+
+    # Move contents from source directory
+    for item in project_dir.iterdir():
+        if item.is_dir():
+            shutil.copytree(item, install_dir / item.name, dirs_exist_ok=True)
+        else:
+            shutil.copy2(item, install_dir / item.name)
+
+    typer.secho(
+        f"🎊 Successfully installed {project_name} to {install_dir}.",
+        fg=typer.colors.GREEN,
+        bold=True,
+    )
+
+    return install_dir
+
+
+def _verify_hashes(list_content: str, tmpdir: Path) -> bool:
+    """Verify file hashes based on the LIST content."""
+    for line in list_content.strip().split("\n"):
+        rel_path, hash_expected, _ = line.split(",")
+        file_path = tmpdir / rel_path
+        if not file_path.exists() or get_sha256_hash(file_path) != hash_expected:
+            return False
+    return True
+
+
+def _validate_fab_and_config_metadata(
+    fab_name: str, config_metadata: tuple[str, str, str, str]
+) -> None:
+    """Validate metadata from the FAB filename and config."""
+    publisher, project_name, version, fab_hash = config_metadata
+
+    fab_name = fab_name.removesuffix(".fab")
+
+    fab_publisher, fab_project_name, fab_version, fab_shorthash = fab_name.split(".")
+    fab_version = fab_version.replace("-", ".")
+
+    # Check FAB filename format
+    if (
+        f"{fab_publisher}.{fab_project_name}.{fab_version}"
+        != f"{publisher}.{project_name}.{version}"
+        or len(fab_shorthash) != FAB_HASH_TRUNCATION  # Verify hash length
+    ):
+        typer.secho(
+            "❌ FAB file has incorrect name. The file name must follow the format "
+            "`<publisher>.<project_name>.<version>.<8hexchars>.fab`.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Verify hash is a valid hexadecimal
+    try:
+        _ = int(fab_shorthash, 16)
+    except Exception as e:
+        typer.secho(
+            f"❌ FAB file has an invalid hexadecimal string `{fab_shorthash}`.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1) from e
+
+    # Verify shorthash matches
+    if fab_shorthash != fab_hash[:FAB_HASH_TRUNCATION]:
+        typer.secho(
+            "❌ The hash in the FAB file name does not match the hash of the FAB.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)

flwr/cli/log.py

@@ -0,0 +1,182 @@
+# 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 `log` command."""
+
+
+import time
+from logging import DEBUG, ERROR, INFO
+from pathlib import Path
+from typing import Annotated, Any, Optional, cast
+
+import grpc
+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 CONN_RECONNECT_INTERVAL, CONN_REFRESH_PERIOD
+from flwr.common.logger import log as logger
+from flwr.proto.exec_pb2 import StreamLogsRequest  # 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 start_stream(
+    run_id: int, channel: grpc.Channel, refresh_period: int = CONN_REFRESH_PERIOD
+) -> None:
+    """Start log streaming for a given run ID."""
+    stub = ExecStub(channel)
+    after_timestamp = 0.0
+    try:
+        logger(INFO, "Starting logstream for run_id `%s`", run_id)
+        while True:
+            after_timestamp = stream_logs(run_id, stub, refresh_period, after_timestamp)
+            time.sleep(CONN_RECONNECT_INTERVAL)
+            logger(DEBUG, "Reconnecting to logstream")
+    except KeyboardInterrupt:
+        logger(INFO, "Exiting logstream")
+    except grpc.RpcError as e:
+        # pylint: disable=E1101
+        if e.code() == grpc.StatusCode.NOT_FOUND:
+            logger(ERROR, "Invalid run_id `%s`, exiting", run_id)
+        if e.code() == grpc.StatusCode.CANCELLED:
+            pass
+    finally:
+        channel.close()
+
+
+def stream_logs(
+    run_id: int, stub: ExecStub, duration: int, after_timestamp: float
+) -> float:
+    """Stream logs from the beginning of a run with connection refresh.
+
+    Parameters
+    ----------
+    run_id : int
+        The identifier of the run.
+    stub : ExecStub
+        The gRPC stub to interact with the Exec service.
+    duration : int
+        The timeout duration for each stream connection in seconds.
+    after_timestamp : float
+        The timestamp to start streaming logs from.
+
+    Returns
+    -------
+    float
+        The latest timestamp from the streamed logs or the provided `after_timestamp`
+        if no logs are returned.
+    """
+    req = StreamLogsRequest(run_id=run_id, after_timestamp=after_timestamp)
+
+    latest_timestamp = 0.0
+    res = None
+    try:
+        with unauthenticated_exc_handler():
+            for res in stub.StreamLogs(req, timeout=duration):
+                print(res.log_output, end="")
+    except grpc.RpcError as e:
+        # pylint: disable=E1101
+        if e.code() != grpc.StatusCode.DEADLINE_EXCEEDED:
+            raise e
+    finally:
+        if res is not None:
+            latest_timestamp = cast(float, res.latest_timestamp)
+
+    return max(latest_timestamp, after_timestamp)
+
+
+def print_logs(run_id: int, channel: grpc.Channel, timeout: int) -> None:
+    """Print logs from the beginning of a run."""
+    stub = ExecStub(channel)
+    req = StreamLogsRequest(run_id=run_id)
+
+    try:
+        while True:
+            try:
+                with unauthenticated_exc_handler():
+                    # Enforce timeout for graceful exit
+                    for res in stub.StreamLogs(req, timeout=timeout):
+                        print(res.log_output)
+            except grpc.RpcError as e:
+                # pylint: disable=E1101
+                if e.code() == grpc.StatusCode.DEADLINE_EXCEEDED:
+                    break
+                if e.code() == grpc.StatusCode.NOT_FOUND:
+                    logger(ERROR, "Invalid run_id `%s`, exiting", run_id)
+                    break
+                if e.code() == grpc.StatusCode.CANCELLED:
+                    break
+    except KeyboardInterrupt:
+        logger(DEBUG, "Stream interrupted by user")
+    finally:
+        channel.close()
+        logger(DEBUG, "Channel closed")
+
+
+def log(
+    run_id: Annotated[
+        int,
+        typer.Argument(help="The Flower run ID to query"),
+    ],
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower project to run"),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation to run the app on"),
+    ] = None,
+    stream: Annotated[
+        bool,
+        typer.Option(
+            "--stream/--show",
+            help="Flag to stream or print logs from the Flower run",
+        ),
+    ] = True,
+) -> None:
+    """Get logs from a Flower project run."""
+    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
+    )
+    exit_if_no_address(federation_config, "log")
+
+    _log_with_exec_api(app, federation, federation_config, run_id, stream)
+
+
+def _log_with_exec_api(
+    app: Path,
+    federation: str,
+    federation_config: dict[str, Any],
+    run_id: int,
+    stream: bool,
+) -> None:
+    auth_plugin = try_obtain_cli_auth_plugin(app, federation)
+    channel = init_channel(app, federation_config, auth_plugin)
+
+    if stream:
+        start_stream(run_id, channel, CONN_REFRESH_PERIOD)
+    else:
+        logger(INFO, "Printing logstream for run_id `%s`", run_id)
+        print_logs(run_id, channel, timeout=5)

flwr/{server/superlink/state → cli/login}/__init__.py

@@ -1,4 +1,4 @@
-# Copyright 2023 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -12,17 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower server state."""
+"""Flower command line interface `login` command."""
 
 
-from .in_memory_state import InMemoryState as InMemoryState
-from .sqlite_state import SqliteState as SqliteState
-from .state import State as State
-from .state_factory import StateFactory as StateFactory
+from .login import login as login
 
 __all__ = [
-    "InMemoryState",
-    "SqliteState",
-    "State",
-    "StateFactory",
+    "login",
 ]

flwr/cli/login/login.py

@@ -0,0 +1,88 @@
+# 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 `login` 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.typing import UserAuthLoginDetails
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    GetLoginDetailsRequest,
+    GetLoginDetailsResponse,
+)
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+from ..utils import init_channel, try_obtain_cli_auth_plugin
+
+
+def login(  # pylint: disable=R0914
+    app: Annotated[
+        Path,
+        typer.Argument(help="Path of the Flower App to run."),
+    ] = Path("."),
+    federation: Annotated[
+        Optional[str],
+        typer.Argument(help="Name of the federation to login into."),
+    ] = None,
+) -> None:
+    """Login to Flower SuperLink."""
+    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
+    )
+    exit_if_no_address(federation_config, "login")
+    channel = init_channel(app, federation_config, None)
+    stub = ExecStub(channel)
+
+    login_request = GetLoginDetailsRequest()
+    login_response: GetLoginDetailsResponse = stub.GetLoginDetails(login_request)
+
+    # Get the auth plugin
+    auth_type = login_response.auth_type
+    auth_plugin = try_obtain_cli_auth_plugin(app, federation, auth_type)
+    if auth_plugin is None:
+        typer.secho(
+            f'❌ Authentication type "{auth_type}" not found',
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Login
+    details = UserAuthLoginDetails(
+        auth_type=login_response.auth_type,
+        device_code=login_response.device_code,
+        verification_uri_complete=login_response.verification_uri_complete,
+        expires_in=login_response.expires_in,
+        interval=login_response.interval,
+    )
+    credentials = auth_plugin.login(details, stub)
+
+    # Store the tokens
+    auth_plugin.store_tokens(credentials)