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

flwr/__init__.py

@@ -15,18 +15,29 @@
 """Flower main package."""
 
 
+import importlib
+
 from flwr.common.version import package_version as _package_version
 
-from . import app, client, clientapp, common, server, serverapp, simulation
+from . import app, clientapp, serverapp
 
 __all__ = [
     "app",
-    "client",
     "clientapp",
-    "common",
-    "server",
     "serverapp",
-    "simulation",
 ]
 
 __version__ = _package_version
+
+
+# Lazy imports for legacy support
+_lazy_imports = {"simulation", "server", "client", "common"}
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import for legacy support."""
+    if name in _lazy_imports:
+        module = importlib.import_module(f"{__name__}.{name}")
+        globals()[name] = module
+        return module
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

flwr/app/error.py

@@ -17,7 +17,7 @@
 
 from __future__ import annotations
 
-from typing import Optional, cast
+from typing import cast
 
 DEFAULT_TTL = 43200  # This is 12 hours
 MESSAGE_INIT_ERROR_MESSAGE = (
@@ -54,7 +54,7 @@ class Error:
     @property
     def reason(self) -> str | None:
         """Reason reported about the error."""
-        return cast(Optional[str], self.__dict__["_reason"])
+        return cast(str | None, self.__dict__["_reason"])
 
     def __repr__(self) -> str:
         """Return a string representation of this instance."""

flwr/app/exception.py

@@ -15,11 +15,11 @@
 """Flower application exceptions."""
 
 
-class AppExitException(BaseException):
+class AppExitException(Exception):
     """Base exception for all application-level errors in ServerApp and ClientApp.
 
-    When raised, the process will exit and report a telemetry event with the associated
-    exit code. This is not intended to be caught by user code.
+    When raised (and not suppressed), the process will exit and report a telemetry event
+    with the associated exit code.
     """
 
     # Default exit code — subclasses must override

flwr/cli/app.py

@@ -19,7 +19,11 @@ from typer.main import get_command
 
 from flwr.common.version import package_version
 
+from .app_cmd import publish as app_publish
+from .app_cmd import review as app_review
 from .build import build
+from .federation import ls as federation_list
+from .federation import show as federation_show
 from .install import install
 from .log import log
 from .login import login
@@ -63,6 +67,21 @@ supernode_app.command("list")(supernode_list)
 supernode_app.command(hidden=True)(supernode_list)
 app.add_typer(supernode_app, name="supernode")
 
+# Create app command group
+app_app = typer.Typer(help="Manage Apps")
+app_app.command()(app_review)
+app_app.command()(app_publish)
+app.add_typer(app_app, name="app")
+
+# Create federation command group
+federation_app = typer.Typer(help="Manage Federations")
+# Make it appear as "list"
+federation_app.command("list")(federation_list)
+# Hide "ls" command (left as alias)
+federation_app.command(hidden=True)(federation_list)
+app.add_typer(federation_app, name="federation")
+federation_app.command()(federation_show)
+
 typer_click_object = get_command(app)
 
 

flwr/cli/app_cmd/__init__.py

@@ -0,0 +1,23 @@
+# 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 `app` command."""
+
+from .publish import publish as publish
+from .review import review as review
+
+__all__ = [
+    "publish",
+    "review",
+]

flwr/cli/app_cmd/publish.py

@@ -0,0 +1,285 @@
+# 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 `app publish` command."""
+
+
+from contextlib import ExitStack
+from pathlib import Path
+from typing import IO, Annotated
+
+import requests
+import typer
+from requests import Response
+
+from flwr.common.constant import FAB_CONFIG_FILE
+from flwr.common.version import package_version as flwr_version
+from flwr.supercore.constant import (
+    APP_PUBLISH_EXCLUDE_PATTERNS,
+    APP_PUBLISH_INCLUDE_PATTERNS,
+    MAX_DIR_DEPTH,
+    MAX_FILE_BYTES,
+    MAX_FILE_COUNT,
+    MAX_TOTAL_BYTES,
+    MIME_MAP,
+    PLATFORM_API_URL,
+    UTF8,
+)
+
+from ..auth_plugin.oidc_cli_plugin import OidcCliPlugin
+from ..config_utils import (
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from ..constant import FEDERATION_CONFIG_HELP_MESSAGE
+from ..utils import build_pathspec, load_cli_auth_plugin, load_gitignore_patterns
+
+
+# pylint: disable=too-many-locals
+def publish(
+    app: Annotated[
+        Path,
+        typer.Argument(
+            help="Project directory to upload (defaults to current directory)."
+        ),
+    ] = Path("."),
+    federation: Annotated[
+        str | None,
+        typer.Argument(
+            help="Name of the federation used for login before publishing app."
+        ),
+    ] = None,
+    federation_config_overrides: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--federation-config",
+            help=FEDERATION_CONFIG_HELP_MESSAGE,
+        ),
+    ] = None,
+) -> None:
+    """Publish a Flower App to the Flower Platform.
+
+    This command uploads your app project to the Flower Platform. Files are filtered
+    based on .gitignore patterns and allowed file extensions.
+    """
+    # Load configs
+    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, federation_config_overrides
+    )
+
+    # Load the authentication plugin
+    auth_plugin = load_cli_auth_plugin(app, federation, federation_config)
+    auth_plugin.load_tokens()
+    if not isinstance(auth_plugin, OidcCliPlugin) or not auth_plugin.access_token:
+        typer.secho(
+            "❌ Please log in before publishing app.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Load token from the plugin
+    token = auth_plugin.access_token
+
+    # Collect & validate app files
+    file_paths = _collect_file_paths(app)
+    _validate_files(file_paths)
+
+    # Build and POST multipart
+    with ExitStack() as stack:
+        files_param = _build_multipart_files_param(app, file_paths, stack)
+        try:
+            resp = _post_files(files_param, token)
+        except requests.RequestException as err:
+            typer.secho(f"❌ Network error: {err}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1) from err
+
+    if resp.ok:
+        typer.secho("🎊 Upload successful", fg=typer.colors.GREEN, bold=True)
+        return  # success
+
+    # Error path:
+    msg = f"❌ Upload failed with status {resp.status_code}"
+    if resp.text:
+        msg += f": {resp.text}"
+    typer.secho(msg, fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)
+
+
+def _depth_of(relative_path_to_root: Path) -> int:
+    """Return depth that is number of parts (directories) in the relative path
+    (excluding filename).
+
+    Example: "a/b/c.py" -> depth 2
+    Interpret "directory depth" as number of directories: len(parts) - 1
+    """
+    return max(0, len(relative_path_to_root.parts) - 1)
+
+
+def _detect_mime(path: Path) -> str:
+    """Detect files' MIME."""
+    return MIME_MAP.get(path.suffix.lower(), "text/plain; charset=utf-8")
+
+
+def _collect_file_paths(root: Path) -> list[Path]:
+    """Return list of file paths that match include/exclude patterns."""
+    # Build include/exclude pathspecs
+    # Note: This should be a temporary solution until we have a complete mechanism
+    # for configurable inclusion and exclusion rules.
+    # Note: Unlike Git, we do not support nested .gitignore files in subdirectories.
+    gitignore_patterns = tuple(load_gitignore_patterns(root / ".gitignore"))
+    exclude_pathspec = build_pathspec(gitignore_patterns + APP_PUBLISH_EXCLUDE_PATTERNS)
+    include_pathspec = build_pathspec(APP_PUBLISH_INCLUDE_PATTERNS)
+
+    # Walk the directory tree
+    file_paths: list[Path] = []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+
+        # Skip excluded or not included files
+        # Note: pathspec requires POSIX style relative paths
+        relative_path = path.relative_to(root)
+        posix = relative_path.as_posix()
+        if exclude_pathspec.match_file(posix) or not include_pathspec.match_file(posix):
+            typer.echo(typer.style(f"Skip: {path}", fg=typer.colors.YELLOW))
+            continue
+
+        # Check max depth
+        if _depth_of(relative_path) > MAX_DIR_DEPTH:
+            typer.secho(
+                f"Error: '{path}' "
+                f"exceeds the maximum directory depth "
+                f"of {MAX_DIR_DEPTH}.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=2)
+
+        file_paths.append(path)
+
+    # Sort for deterministic ordering
+    file_paths.sort(key=lambda path: path.as_posix())
+    return file_paths
+
+
+def _validate_files(file_paths: list[Path]) -> None:
+    """Validate files against upload constraints.
+
+    Checks file count, individual file size, total size, and UTF-8 encoding.
+    """
+    if len(file_paths) == 0:
+        typer.secho(
+            "Nothing to upload: no files matched after applying .gitignore and "
+            "allowed extensions.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    if len(file_paths) > MAX_FILE_COUNT:
+        typer.secho(
+            f"Too many files: {len(file_paths)} > allowed maximum of {MAX_FILE_COUNT}.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # Calculate files size
+    total_size = 0
+    for path in file_paths:
+        file_size = path.stat().st_size
+        total_size += file_size
+
+        # Check single file size
+        if file_size > MAX_FILE_BYTES:
+            typer.secho(
+                f"File too large: '{path.as_posix()}' is {file_size:,} bytes, "
+                f"exceeding the per-file limit of {MAX_FILE_BYTES:,} bytes.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=2)
+
+        # Ensure we can decode as UTF-8.
+        try:
+            path.read_text(encoding=UTF8)
+        except UnicodeDecodeError as err:
+            typer.secho(
+                f"Encoding error: '{path}' is not UTF-8 encoded.",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            raise typer.Exit(code=2) from err
+
+    # Check total files size
+    if total_size > MAX_TOTAL_BYTES:
+        typer.secho(
+            "Total size of all files is too large: "
+            f"{total_size:,} bytes > {MAX_TOTAL_BYTES:,} bytes.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+    # Print validation passed prompt
+    typer.echo(typer.style("✅ Validation passed", fg=typer.colors.GREEN, bold=True))
+    typer.echo(f"{len(file_paths)} files, {total_size:,} bytes in total")
+
+
+def _build_multipart_files_param(
+    root: Path,
+    file_paths: list[Path],
+    stack: ExitStack,
+) -> list[tuple[str, tuple[str, IO[bytes], str]]]:
+    """Build multipart/form-data files parameter for HTTP upload.
+
+    Returns list of tuples: (field_name, (filename, file_object, content_type)).
+    File handles are registered with ExitStack for proper cleanup.
+    """
+    form: list[tuple[str, tuple[str, IO[bytes], str]]] = []
+    for path in file_paths:
+        # Detect MIME (content type)
+        mime = _detect_mime(path)
+
+        # Open file and register with ExitStack
+        # pylint: disable-next=consider-using-with
+        fobj = stack.enter_context(open(path.resolve(), "rb"))
+        typer.echo(f"Attach {path} ({mime}, {path.stat().st_size:,} bytes)")
+
+        # Get relative POSIX path
+        relative_posix = path.relative_to(root).as_posix()
+
+        # Append to form data (key, (filename, fileobj, mime))
+        form.append(("files", (relative_posix, fobj, mime)))
+    return form
+
+
+def _post_files(
+    files_param: list[tuple[str, tuple[str, IO[bytes], str]]],
+    token: str,
+) -> Response:
+    """POST multipart with one part per file."""
+    url = f"{PLATFORM_API_URL}/hub/apps/publish"
+    headers = {"Authorization": f"Bearer {token}"}
+    body = {"flwr_version": flwr_version}
+
+    resp = requests.post(
+        url, files=files_param, headers=headers, json=body, timeout=120
+    )
+    return resp

flwr/cli/app_cmd/review.py

@@ -0,0 +1,252 @@
+# 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 `app review` command."""
+
+
+import base64
+import hashlib
+import re
+from pathlib import Path
+from typing import Annotated
+
+import requests
+import typer
+from cryptography.exceptions import UnsupportedAlgorithm
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from flwr.common import now
+from flwr.common.config import get_flwr_dir
+from flwr.common.constant import FAB_CONFIG_FILE
+from flwr.common.version import package_version as flwr_version
+from flwr.supercore.constant import PLATFORM_API_URL
+from flwr.supercore.primitives.asymmetric_ed25519 import (
+    create_message_to_sign,
+    load_private_key,
+    sign_message,
+)
+
+from ..auth_plugin.oidc_cli_plugin import OidcCliPlugin
+from ..config_utils import (
+    load_and_validate,
+    process_loaded_project_config,
+    validate_federation_in_project_config,
+)
+from ..constant import FEDERATION_CONFIG_HELP_MESSAGE
+from ..install import install_from_fab
+from ..utils import load_cli_auth_plugin, parse_app_spec, request_download_link
+
+TRY_AGAIN_MESSAGE = "Please try again or press CTRL+C to abort.\n"
+
+
+# pylint: disable-next=too-many-locals, too-many-statements
+def review(
+    app_spec: Annotated[
+        str,
+        typer.Argument(
+            help="App specifier (e.g., '@account/app' or '@account/app==1.0.0'). "
+            "Version is optional; defaults to the latest."
+        ),
+    ],
+    app_dir_login: Annotated[
+        Path,
+        typer.Argument(
+            help="Project directory to used for login before reviewing app."
+        ),
+    ] = Path("."),
+    federation: Annotated[
+        str | None,
+        typer.Argument(
+            help="Name of the federation used for login before reviewing app."
+        ),
+    ] = None,
+    federation_config_overrides: Annotated[
+        list[str] | None,
+        typer.Option(
+            "--federation-config",
+            help=FEDERATION_CONFIG_HELP_MESSAGE,
+        ),
+    ] = None,
+) -> None:
+    """Download a FAB for <APP-ID>, unpack it for manual review, and upon confirmation
+    sign & submit the review to the Platform."""
+    # Load configs
+    pyproject_path = app_dir_login / FAB_CONFIG_FILE if app_dir_login 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, federation_config_overrides
+    )
+
+    # Load the authentication plugin
+    auth_plugin = load_cli_auth_plugin(app_dir_login, federation, federation_config)
+    auth_plugin.load_tokens()
+    if not isinstance(auth_plugin, OidcCliPlugin) or not auth_plugin.access_token:
+        typer.secho(
+            "❌ Please log in before reviewing app.",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    # Load token from the plugin
+    token = auth_plugin.access_token
+
+    # Validate app version and ID format
+    app_id, app_version = parse_app_spec(app_spec)
+
+    # Download FAB
+    typer.secho("Downloading FAB... ", fg=typer.colors.BLUE)
+    url = f"{PLATFORM_API_URL}/hub/fetch-fab"
+    presigned_url = request_download_link(app_id, app_version, url, "fab_url")
+    fab_bytes = _download_fab(presigned_url)
+
+    # Unpack FAB
+    typer.secho("Unpacking FAB... ", fg=typer.colors.BLUE)
+    review_dir = _create_review_dir()
+    review_app_path = install_from_fab(fab_bytes, review_dir)
+
+    # Extract app version
+    version_pattern = re.compile(r"\b(\d+\.\d+\.\d+)\b")
+    match = version_pattern.search(str(review_app_path))
+    assert match is not None
+    app_version = match.group(1)
+
+    # Prompt to ask for sign
+    typer.secho(
+        f"""
+    Review the unpacked app in the following directory:
+
+        {typer.style(review_app_path, fg=typer.colors.GREEN, bold=True)}
+
+    If you have reviewed the app and want to continue to sign it,
+    type {typer.style("SIGN", fg=typer.colors.GREEN, bold=True)} or abort with CTRL+C.
+    """,
+        fg=typer.colors.BLUE,
+    )
+
+    confirmation = typer.prompt("Type SIGN to continue").strip()
+    if confirmation.upper() != "SIGN":
+        typer.secho("Aborted (user did not type SIGN).", fg=typer.colors.YELLOW)
+        raise typer.Exit(code=130)
+
+    # Ask for private key path (retry until valid)
+    while True:
+        try:
+            key_path_str = typer.prompt(
+                "Please specify the path of Ed25519 OpenSSH private key for signing"
+            )
+        except typer.Abort as e:
+            typer.secho("Aborted by user.", fg=typer.colors.YELLOW, err=True)
+            raise typer.Exit(code=130) from e
+
+        key_path = Path(key_path_str).expanduser().resolve()
+
+        if not key_path.is_file():
+            typer.secho(
+                f"❌ Private key not found: {key_path}",
+                fg=typer.colors.RED,
+                err=True,
+            )
+            typer.secho(TRY_AGAIN_MESSAGE, fg=typer.colors.YELLOW)
+            continue
+
+        # Load private key
+        try:
+            private_key = load_private_key(key_path)
+        except (OSError, ValueError, UnsupportedAlgorithm) as e:
+            typer.secho(
+                f"❌ Failed to load the private key: {e}", fg=typer.colors.RED, err=True
+            )
+            typer.secho(TRY_AGAIN_MESSAGE, fg=typer.colors.YELLOW)
+            continue
+        break  # valid
+
+    # Sign FAB
+    signature, signed_at = _sign_fab(fab_bytes, private_key)
+
+    # Submit review
+    _submit_review(app_id, app_version, signature, signed_at, token)
+
+
+def _create_review_dir() -> Path:
+    """Create a directory for reviewing code."""
+    home = get_flwr_dir()
+    review_dir = home / "reviews"
+    review_dir.mkdir(parents=True, exist_ok=True)
+    return review_dir
+
+
+def _download_fab(url: str) -> bytes:
+    """Download FAB file from given URL."""
+    try:
+        r = requests.get(url, timeout=60)
+        r.raise_for_status()
+    except requests.RequestException as e:
+        typer.secho(
+            f"❌ FAB download failed: {e}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1) from e
+    return r.content
+
+
+def _sign_fab(
+    fab_bytes: bytes, private_key: ed25519.Ed25519PrivateKey
+) -> tuple[bytes, int]:
+    """Sign the given FAB hash bytes."""
+    # Get current timestamp
+    timestamp = int(now().timestamp())
+    message_to_sign = create_message_to_sign(
+        hashlib.sha256(fab_bytes).digest(),
+        timestamp,
+    )
+    return sign_message(private_key, message_to_sign), timestamp
+
+
+def _submit_review(
+    app_id: str, app_version: str, signature: bytes, signed_at: int, token: str
+) -> None:
+    """Submit review to Flower Platform API."""
+    signature_b64 = base64.urlsafe_b64encode(signature).rstrip(b"=").decode("ascii")
+    url = f"{PLATFORM_API_URL}/hub/apps/signature"
+    headers = {"Authorization": f"Bearer {token}", "Content-Type": "application/json"}
+    payload = {
+        "app_id": app_id,
+        "app_version": app_version,
+        "signature_b64": signature_b64,
+        "signed_at": signed_at,
+        "flwr_version": flwr_version,
+    }
+    try:
+        resp = requests.post(url, headers=headers, json=payload, timeout=120)
+    except requests.RequestException as e:
+        typer.secho(
+            f"❌ Network error while submitting review: {e}",
+            fg=typer.colors.RED,
+            err=True,
+        )
+        raise typer.Exit(code=1) from e
+
+    if resp.ok:
+        typer.secho("🎊 Review submitted", fg=typer.colors.GREEN, bold=True)
+        return
+
+    # Error path:
+    msg = f"❌ Review submission failed (HTTP {resp.status_code})"
+    if resp.text:
+        msg += f": {resp.text}"
+    typer.secho(msg, fg=typer.colors.RED, err=True)
+    raise typer.Exit(code=1)

flwr/cli/auth_plugin/auth_plugin.py

@@ -18,7 +18,6 @@
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
 from pathlib import Path
-from typing import Optional, Union
 
 from flwr.common.typing import AccountAuthCredentials, AccountAuthLoginDetails
 from flwr.proto.control_pb2_grpc import ControlStub
@@ -84,12 +83,12 @@ class CliAuthPlugin(ABC):
 
     @abstractmethod
     def write_tokens_to_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Sequence[tuple[str, Union[str, bytes]]]:
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> Sequence[tuple[str, str | bytes]]:
         """Write authentication tokens to the provided metadata."""
 
     @abstractmethod
     def read_tokens_from_metadata(
-        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> Optional[AccountAuthCredentials]:
+        self, metadata: Sequence[tuple[str, str | bytes]]
+    ) -> AccountAuthCredentials | None:
         """Read authentication tokens from the provided metadata."""