flwr 1.13.1__py3-none-any.whl → 1.15.0__py3-none-any.whl

flwr/cli/app.py

@@ -14,15 +14,18 @@
 # ==============================================================================
 """Flower command line interface."""
 
+
 import typer
 from typer.main import get_command
 
 from .build import build
 from .install import install
 from .log import log
+from .login import login
 from .ls import ls
 from .new import new
 from .run import run
+from .stop import stop
 
 app = typer.Typer(
     help=typer.style(
@@ -39,6 +42,8 @@ app.command()(build)
 app.command()(install)
 app.command()(log)
 app.command()(ls)
+app.command()(stop)
+app.command()(login)
 
 typer_click_object = get_command(app)
 

flwr/cli/auth_plugin/__init__.py

@@ -0,0 +1,31 @@
+# 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 user auth plugins."""
+
+
+from flwr.common.auth_plugin import CliAuthPlugin
+from flwr.common.constant import AuthType
+
+from .oidc_cli_plugin import OidcCliPlugin
+
+
+def get_cli_auth_plugins() -> dict[str, type[CliAuthPlugin]]:
+    """Return all CLI authentication plugins."""
+    return {AuthType.OIDC: OidcCliPlugin}
+
+
+__all__ = [
+    "get_cli_auth_plugins",
+]

flwr/cli/auth_plugin/oidc_cli_plugin.py

@@ -0,0 +1,150 @@
+# 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 CLI user auth plugin for OIDC."""
+
+
+import json
+import time
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any, Optional, Union
+
+import typer
+
+from flwr.common.auth_plugin import CliAuthPlugin
+from flwr.common.constant import (
+    ACCESS_TOKEN_KEY,
+    AUTH_TYPE_KEY,
+    REFRESH_TOKEN_KEY,
+    AuthType,
+)
+from flwr.common.typing import UserAuthCredentials, UserAuthLoginDetails
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    GetAuthTokensRequest,
+    GetAuthTokensResponse,
+)
+from flwr.proto.exec_pb2_grpc import ExecStub
+
+
+class OidcCliPlugin(CliAuthPlugin):
+    """Flower OIDC auth plugin for CLI."""
+
+    def __init__(self, credentials_path: Path):
+        self.access_token: Optional[str] = None
+        self.refresh_token: Optional[str] = None
+        self.credentials_path = credentials_path
+
+    @staticmethod
+    def login(
+        login_details: UserAuthLoginDetails,
+        exec_stub: ExecStub,
+    ) -> UserAuthCredentials:
+        """Authenticate the user and retrieve authentication credentials."""
+        typer.secho(
+            "Please login with your user credentials here: "
+            f"{login_details.verification_uri_complete}",
+            fg=typer.colors.BLUE,
+        )
+        start_time = time.time()
+        time.sleep(login_details.interval)
+
+        while (time.time() - start_time) < login_details.expires_in:
+            res: GetAuthTokensResponse = exec_stub.GetAuthTokens(
+                GetAuthTokensRequest(device_code=login_details.device_code)
+            )
+
+            access_token = res.access_token
+            refresh_token = res.refresh_token
+
+            if access_token and refresh_token:
+                typer.secho(
+                    "✅ Login successful.",
+                    fg=typer.colors.GREEN,
+                    bold=False,
+                )
+                return UserAuthCredentials(
+                    access_token=access_token,
+                    refresh_token=refresh_token,
+                )
+
+            time.sleep(login_details.interval)
+
+        typer.secho(
+            "❌ Timeout, failed to sign in.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)
+
+    def store_tokens(self, credentials: UserAuthCredentials) -> None:
+        """Store authentication tokens to the `credentials_path`.
+
+        The credentials, including tokens, will be saved as a JSON file
+        at `credentials_path`.
+        """
+        self.access_token = credentials.access_token
+        self.refresh_token = credentials.refresh_token
+        json_dict = {
+            AUTH_TYPE_KEY: AuthType.OIDC,
+            ACCESS_TOKEN_KEY: credentials.access_token,
+            REFRESH_TOKEN_KEY: credentials.refresh_token,
+        }
+
+        with open(self.credentials_path, "w", encoding="utf-8") as file:
+            json.dump(json_dict, file, indent=4)
+
+    def load_tokens(self) -> None:
+        """Load authentication tokens from the `credentials_path`."""
+        with open(self.credentials_path, encoding="utf-8") as file:
+            json_dict: dict[str, Any] = json.load(file)
+            access_token = json_dict.get(ACCESS_TOKEN_KEY)
+            refresh_token = json_dict.get(REFRESH_TOKEN_KEY)
+
+        if isinstance(access_token, str) and isinstance(refresh_token, str):
+            self.access_token = access_token
+            self.refresh_token = refresh_token
+
+    def write_tokens_to_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Sequence[tuple[str, Union[str, bytes]]]:
+        """Write authentication tokens to the provided metadata."""
+        if self.access_token is None or self.refresh_token is None:
+            typer.secho(
+                "❌ Missing authentication tokens. Please login first.",
+                fg=typer.colors.RED,
+                bold=True,
+            )
+            raise typer.Exit(code=1)
+
+        return list(metadata) + [
+            (ACCESS_TOKEN_KEY, self.access_token),
+            (REFRESH_TOKEN_KEY, self.refresh_token),
+        ]
+
+    def read_tokens_from_metadata(
+        self, metadata: Sequence[tuple[str, Union[str, bytes]]]
+    ) -> Optional[UserAuthCredentials]:
+        """Read authentication tokens from the provided metadata."""
+        metadata_dict = dict(metadata)
+        access_token = metadata_dict.get(ACCESS_TOKEN_KEY)
+        refresh_token = metadata_dict.get(REFRESH_TOKEN_KEY)
+
+        if isinstance(access_token, str) and isinstance(refresh_token, str):
+            return UserAuthCredentials(
+                access_token=access_token,
+                refresh_token=refresh_token,
+            )
+
+        return None

flwr/cli/build.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `build` command."""
 
+
 import hashlib
 import os
 import shutil

flwr/cli/cli_user_auth_interceptor.py

@@ -0,0 +1,90 @@
+# 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 run interceptor."""
+
+
+from typing import Any, Callable, Union
+
+import grpc
+
+from flwr.common.auth_plugin import CliAuthPlugin
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    StartRunRequest,
+    StreamLogsRequest,
+)
+
+Request = Union[
+    StartRunRequest,
+    StreamLogsRequest,
+]
+
+
+class CliUserAuthInterceptor(
+    grpc.UnaryUnaryClientInterceptor, grpc.UnaryStreamClientInterceptor  # type: ignore
+):
+    """CLI interceptor for user authentication."""
+
+    def __init__(self, auth_plugin: CliAuthPlugin):
+        self.auth_plugin = auth_plugin
+
+    def _authenticated_call(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Send and receive tokens via metadata."""
+        new_metadata = self.auth_plugin.write_tokens_to_metadata(
+            client_call_details.metadata or []
+        )
+
+        details = client_call_details._replace(metadata=new_metadata)
+
+        response = continuation(details, request)
+        if response.initial_metadata():
+            credentials = self.auth_plugin.read_tokens_from_metadata(
+                response.initial_metadata()
+            )
+            # The metadata contains tokens only if they have been refreshed
+            if credentials is not None:
+                self.auth_plugin.store_tokens(credentials)
+
+        return response
+
+    def intercept_unary_unary(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Intercept a unary-unary call for user authentication.
+
+        This method intercepts a unary-unary RPC call initiated from the CLI and adds
+        the required authentication tokens to the RPC metadata.
+        """
+        return self._authenticated_call(continuation, client_call_details, request)
+
+    def intercept_unary_stream(
+        self,
+        continuation: Callable[[Any, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Request,
+    ) -> grpc.Call:
+        """Intercept a unary-stream call for user authentication.
+
+        This method intercepts a unary-stream RPC call initiated from the CLI and adds
+        the required authentication tokens to the RPC metadata.
+        """
+        return self._authenticated_call(continuation, client_call_details, request)

flwr/cli/config_utils.py

@@ -14,53 +14,20 @@
 # ==============================================================================
 """Utility to validate the `pyproject.toml` file."""
 
-import zipfile
-from io import BytesIO
+
 from pathlib import Path
-from typing import IO, Any, Optional, Union, get_args
+from typing import Any, Optional, Union
 
 import tomli
 import typer
 
-from flwr.common import object_ref
-from flwr.common.typing import UserConfigValue
-
-
-def get_fab_config(fab_file: Union[Path, bytes]) -> dict[str, Any]:
-    """Extract the config from a FAB file or path.
-
-    Parameters
-    ----------
-    fab_file : Union[Path, bytes]
-        The Flower App Bundle file to validate and extract the metadata from.
-        It can either be a path to the file or the file itself as bytes.
-
-    Returns
-    -------
-    Dict[str, Any]
-        The `config` of the given Flower App Bundle.
-    """
-    fab_file_archive: Union[Path, IO[bytes]]
-    if isinstance(fab_file, bytes):
-        fab_file_archive = BytesIO(fab_file)
-    elif isinstance(fab_file, Path):
-        fab_file_archive = fab_file
-    else:
-        raise ValueError("fab_file must be either a Path or bytes")
-
-    with zipfile.ZipFile(fab_file_archive, "r") as zipf:
-        with zipf.open("pyproject.toml") as file:
-            toml_content = file.read().decode("utf-8")
-
-        conf = load_from_string(toml_content)
-        if conf is None:
-            raise ValueError("Invalid TOML content in pyproject.toml")
-
-        is_valid, errors, _ = validate(conf, check_module=False)
-        if not is_valid:
-            raise ValueError(errors)
-
-        return conf
+from flwr.common.config import (
+    fuse_dicts,
+    get_fab_config,
+    get_metadata_from_config,
+    parse_config_args,
+    validate_config,
+)
 
 
 def get_fab_metadata(fab_file: Union[Path, bytes]) -> tuple[str, str]:
@@ -77,12 +44,7 @@ def get_fab_metadata(fab_file: Union[Path, bytes]) -> tuple[str, str]:
     Tuple[str, str]
         The `fab_id` and `fab_version` of the given Flower App Bundle.
     """
-    conf = get_fab_config(fab_file)
-
-    return (
-        f"{conf['tool']['flwr']['app']['publisher']}/{conf['project']['name']}",
-        conf["project"]["version"],
-    )
+    return get_metadata_from_config(get_fab_config(fab_file))
 
 
 def load_and_validate(
@@ -119,7 +81,7 @@ def load_and_validate(
         ]
         return (None, errors, [])
 
-    is_valid, errors, warnings = validate(config, check_module, path.parent)
+    is_valid, errors, warnings = validate_config(config, check_module, path.parent)
 
     if not is_valid:
         return (None, errors, warnings)
@@ -132,108 +94,21 @@ def load(toml_path: Path) -> Optional[dict[str, Any]]:
     if not toml_path.is_file():
         return None
 
-    with toml_path.open(encoding="utf-8") as toml_file:
-        return load_from_string(toml_file.read())
-
-
-def _validate_run_config(config_dict: dict[str, Any], errors: list[str]) -> None:
-    for key, value in config_dict.items():
-        if isinstance(value, dict):
-            _validate_run_config(config_dict[key], errors)
-        elif not isinstance(value, get_args(UserConfigValue)):
-            raise ValueError(
-                f"The value for key {key} needs to be of type `int`, `float`, "
-                "`bool, `str`, or  a `dict` of those.",
-            )
-
-
-# pylint: disable=too-many-branches
-def validate_fields(config: dict[str, Any]) -> tuple[bool, list[str], list[str]]:
-    """Validate pyproject.toml fields."""
-    errors = []
-    warnings = []
-
-    if "project" not in config:
-        errors.append("Missing [project] section")
-    else:
-        if "name" not in config["project"]:
-            errors.append('Property "name" missing in [project]')
-        if "version" not in config["project"]:
-            errors.append('Property "version" missing in [project]')
-        if "description" not in config["project"]:
-            warnings.append('Recommended property "description" missing in [project]')
-        if "license" not in config["project"]:
-            warnings.append('Recommended property "license" missing in [project]')
-        if "authors" not in config["project"]:
-            warnings.append('Recommended property "authors" missing in [project]')
-
-    if (
-        "tool" not in config
-        or "flwr" not in config["tool"]
-        or "app" not in config["tool"]["flwr"]
-    ):
-        errors.append("Missing [tool.flwr.app] section")
-    else:
-        if "publisher" not in config["tool"]["flwr"]["app"]:
-            errors.append('Property "publisher" missing in [tool.flwr.app]')
-        if "config" in config["tool"]["flwr"]["app"]:
-            _validate_run_config(config["tool"]["flwr"]["app"]["config"], errors)
-        if "components" not in config["tool"]["flwr"]["app"]:
-            errors.append("Missing [tool.flwr.app.components] section")
-        else:
-            if "serverapp" not in config["tool"]["flwr"]["app"]["components"]:
-                errors.append(
-                    'Property "serverapp" missing in [tool.flwr.app.components]'
-                )
-            if "clientapp" not in config["tool"]["flwr"]["app"]["components"]:
-                errors.append(
-                    'Property "clientapp" missing in [tool.flwr.app.components]'
-                )
-
-    return len(errors) == 0, errors, warnings
-
-
-def validate(
-    config: dict[str, Any],
-    check_module: bool = True,
-    project_dir: Optional[Union[str, Path]] = None,
-) -> tuple[bool, list[str], list[str]]:
-    """Validate pyproject.toml."""
-    is_valid, errors, warnings = validate_fields(config)
-
-    if not is_valid:
-        return False, errors, warnings
-
-    # Validate serverapp
-    serverapp_ref = config["tool"]["flwr"]["app"]["components"]["serverapp"]
-    is_valid, reason = object_ref.validate(serverapp_ref, check_module, project_dir)
+    with toml_path.open("rb") as toml_file:
+        try:
+            return tomli.load(toml_file)
+        except tomli.TOMLDecodeError:
+            return None
 
-    if not is_valid and isinstance(reason, str):
-        return False, [reason], []
-
-    # Validate clientapp
-    clientapp_ref = config["tool"]["flwr"]["app"]["components"]["clientapp"]
-    is_valid, reason = object_ref.validate(clientapp_ref, check_module, project_dir)
-
-    if not is_valid and isinstance(reason, str):
-        return False, [reason], []
-
-    return True, [], []
-
-
-def load_from_string(toml_content: str) -> Optional[dict[str, Any]]:
-    """Load TOML content from a string and return as dict."""
-    try:
-        data = tomli.loads(toml_content)
-        return data
-    except tomli.TOMLDecodeError:
-        return None
 
-
-def validate_project_config(
+def process_loaded_project_config(
     config: Union[dict[str, Any], None], errors: list[str], warnings: list[str]
 ) -> dict[str, Any]:
-    """Validate and return the Flower project configuration."""
+    """Process and return the loaded project configuration.
+
+    This function handles errors and warnings from the `load_and_validate` function,
+    exits on critical issues, and returns the validated configuration.
+    """
     if config is None:
         typer.secho(
             "Project configuration could not be loaded.\n"
@@ -258,7 +133,9 @@ def validate_project_config(
 
 
 def validate_federation_in_project_config(
-    federation: Optional[str], config: dict[str, Any]
+    federation: Optional[str],
+    config: dict[str, Any],
+    overrides: Optional[list[str]] = None,
 ) -> tuple[str, dict[str, Any]]:
     """Validate the federation name in the Flower project configuration."""
     federation = federation or config["tool"]["flwr"]["federations"].get("default")
@@ -288,6 +165,11 @@ def validate_federation_in_project_config(
         )
         raise typer.Exit(code=1)
 
+    # Override the federation configuration if provided
+    if overrides:
+        overrides_dict = parse_config_args(overrides, flatten=False)
+        federation_config = fuse_dicts(federation_config, overrides_dict)
+
     return federation, federation_config
 
 
@@ -300,7 +182,7 @@ def validate_certificate_in_federation_config(
         root_certificates_bytes = (app / root_certificates).read_bytes()
         if insecure := bool(insecure_str):
             typer.secho(
-                "❌ `root_certificates` were provided but the `insecure` parameter "
+                "❌ `root-certificates` were provided but the `insecure` parameter "
                 "is set to `True`.",
                 fg=typer.colors.RED,
                 bold=True,
@@ -324,3 +206,15 @@ def validate_certificate_in_federation_config(
             raise typer.Exit(code=1)
 
     return insecure, root_certificates_bytes
+
+
+def exit_if_no_address(federation_config: dict[str, Any], cmd: str) -> None:
+    """Exit if the provided federation_config has no "address" key."""
+    if "address" not in federation_config:
+        typer.secho(
+            f"❌ `flwr {cmd}` currently works with a SuperLink. Ensure that the correct"
+            "SuperLink (Exec API) address is provided in `pyproject.toml`.",
+            fg=typer.colors.RED,
+            bold=True,
+        )
+        raise typer.Exit(code=1)

flwr/cli/constant.py

@@ -0,0 +1,27 @@
+# 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.
+# ==============================================================================
+"""Constants for CLI commands."""
+
+
+# The help message for `--federation-config` option
+FEDERATION_CONFIG_HELP_MESSAGE = (
+    "Override federation configuration values in the format:\n\n"
+    "`--federation-config 'key1=value1 key2=value2' --federation-config "
+    "'key3=value3'`\n\nValues can be of any type supported in TOML, such as "
+    "bool, int, float, or string. Ensure that the keys (`key1`, `key2`, `key3` "
+    "in this example) exist in the federation configuration under the "
+    "`[tool.flwr.federations.<YOUR_FEDERATION>]` table of the `pyproject.toml` "
+    "for proper overriding."
+)

flwr/cli/example.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `example` command."""
 
+
 import json
 import os
 import subprocess

flwr/cli/install.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower command line interface `install` command."""
 
+
 import hashlib
 import shutil
 import tempfile
@@ -153,7 +154,7 @@ def validate_and_install(
         )
         raise typer.Exit(code=1)
 
-    version, fab_id = get_metadata_from_config(config)
+    fab_id, version = get_metadata_from_config(config)
     publisher, project_name = fab_id.split("/")
     config_metadata = (publisher, project_name, version, fab_hash)