flwr-nightly 1.13.0.dev20241109__py3-none-any.whl → 1.13.0.dev20241112__py3-none-any.whl

flwr/cli/build.py

@@ -19,14 +19,18 @@ import os
 import shutil
 import tempfile
 import zipfile
+from logging import DEBUG, ERROR
 from pathlib import Path
 from typing import Annotated, Any, Optional, Union
 
 import pathspec
 import tomli_w
 import typer
+from hatchling.builders.wheel import WheelBuilder
+from hatchling.metadata.core import ProjectMetadata
 
 from flwr.common.constant import FAB_ALLOWED_EXTENSIONS, FAB_DATE, FAB_HASH_TRUNCATION
+from flwr.common.logger import log
 
 from .config_utils import load_and_validate
 from .utils import is_valid_project_name
@@ -51,6 +55,27 @@ def get_fab_filename(conf: dict[str, Any], fab_hash: str) -> str:
     return f"{publisher}.{name}.{version}.{fab_hash_truncated}.fab"
 
 
+def _build_app_wheel(app: Path) -> Path:
+    """Build app as a wheel and return its path."""
+    # Path to your project directory
+    app_dir = str(app.resolve())
+    try:
+
+        # Initialize the WheelBuilder
+        builder = WheelBuilder(
+            app_dir, metadata=ProjectMetadata(root=app_dir, plugin_manager=None)
+        )
+
+        # Build
+        whl_path = Path(next(builder.build(directory=app_dir)))
+        log(DEBUG, "Wheel succesfully built: %s", str(whl_path))
+    except Exception as ex:
+        log(ERROR, "Exception encountered when building wheel.", exc_info=ex)
+        raise typer.Exit(code=1) from ex
+
+    return whl_path
+
+
 # pylint: disable=too-many-locals, too-many-statements
 def build(
     app: Annotated[
@@ -106,6 +131,12 @@ def build(
             bold=True,
         )
 
+    # Build wheel
+    whl_path = _build_app_wheel(app)
+
+    # Add path to .whl to `[tool.flwr.app]`
+    conf["tool"]["flwr"]["app"]["whl"] = str(whl_path.name)
+
     # Load .gitignore rules if present
     ignore_spec = _load_gitignore(app)
 
@@ -137,6 +168,9 @@ def build(
                 and f.name != "pyproject.toml"  # Exclude the original pyproject.toml
             ]
 
+            # Include FAB .whl
+            all_files.append(whl_path)
+
             for file_path in all_files:
                 # Read the file content manually
                 with open(file_path, "rb") as f:
@@ -153,6 +187,9 @@ def build(
             # Add CONTENT and CONTENT.jwt to the zip file
             write_to_zip(fab_file, ".info/CONTENT", list_file_content)
 
+    # Erase FAB .whl in app directory
+    whl_path.unlink()
+
     # Get hash of FAB file
     content = Path(temp_filename).read_bytes()
     fab_hash = hashlib.sha256(content).hexdigest()

flwr/cli/install.py

@@ -188,23 +188,25 @@ def validate_and_install(
         else:
             shutil.copy2(item, install_dir / item.name)
 
+    whl_file = config["tool"]["flwr"]["app"]["whl"]
+    install_whl = install_dir / whl_file
     try:
         subprocess.run(
-            ["pip", "install", "-e", install_dir, "--no-deps"],
+            ["pip", "install", "--no-deps", install_whl],
             capture_output=True,
             text=True,
             check=True,
         )
     except subprocess.CalledProcessError as e:
         typer.secho(
-            f"❌ Failed to `pip install` package(s) from {install_dir}:\n{e.stderr}",
+            f"❌ Failed to install {project_name}:\n{e.stderr}",
             fg=typer.colors.RED,
             bold=True,
         )
         raise typer.Exit(code=1) from e
 
     typer.secho(
-        f"🎊 Successfully installed {project_name} to {install_dir}.",
+        f"🎊 Successfully installed {project_name}.",
         fg=typer.colors.GREEN,
         bold=True,
     )

flwr/client/clientapp/app.py

@@ -24,6 +24,8 @@ import grpc
 from flwr.cli.install import install_from_fab
 from flwr.client.client_app import ClientApp, LoadClientAppError
 from flwr.common import Context, Message
+from flwr.common.args import add_args_flwr_app_common
+from flwr.common.config import get_flwr_dir
 from flwr.common.constant import ErrorCode
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
@@ -60,7 +62,7 @@ def flwr_clientapp() -> None:
     parser.add_argument(
         "--supernode",
         type=str,
-        help="Address of SuperNode ClientAppIo gRPC servicer",
+        help="Address of SuperNode's ClientAppIo API",
     )
     parser.add_argument(
         "--token",
@@ -68,17 +70,24 @@ def flwr_clientapp() -> None:
         required=False,
         help="Unique token generated by SuperNode for each ClientApp execution",
     )
+    add_args_flwr_app_common(parser=parser)
     args = parser.parse_args()
 
     log(INFO, "Starting Flower ClientApp")
+
     log(
         DEBUG,
-        "Staring isolated `ClientApp` connected to SuperNode ClientAppIo at %s "
+        "Starting isolated `ClientApp` connected to SuperNode's ClientAppIo API at %s "
         "with token %s",
         args.supernode,
         args.token,
     )
-    run_clientapp(supernode=args.supernode, token=args.token)
+    run_clientapp(
+        supernode=args.supernode,
+        run_once=(args.token is not None),
+        token=args.token,
+        flwr_dir=args.flwr_dir,
+    )
 
 
 def on_channel_state_change(channel_connectivity: str) -> None:
@@ -88,27 +97,23 @@ def on_channel_state_change(channel_connectivity: str) -> None:
 
 def run_clientapp(  # pylint: disable=R0914
     supernode: str,
+    run_once: bool,
     token: Optional[int] = None,
+    flwr_dir: Optional[str] = None,
 ) -> None:
-    """Run Flower ClientApp process.
-
-    Parameters
-    ----------
-    supernode : str
-        Address of SuperNode
-    token : Optional[int] (default: None)
-        Unique SuperNode token for ClientApp-SuperNode authentication
-    """
+    """Run Flower ClientApp process."""
     channel = create_channel(
         server_address=supernode,
         insecure=True,
     )
     channel.subscribe(on_channel_state_change)
 
+    # Resolve directory where FABs are installed
+    flwr_dir_ = get_flwr_dir(flwr_dir)
+
     try:
         stub = ClientAppIoStub(channel)
 
-        only_once = token is not None
         while True:
             # If token is not set, loop until token is received from SuperNode
             while token is None:
@@ -121,13 +126,13 @@ def run_clientapp(  # pylint: disable=R0914
             # Install FAB, if provided
             if fab:
                 log(DEBUG, "Flower ClientApp starts FAB installation.")
-                install_from_fab(fab.content, flwr_dir=None, skip_prompt=True)
+                install_from_fab(fab.content, flwr_dir=flwr_dir_, skip_prompt=True)
 
             load_client_app_fn = get_load_client_app_fn(
                 default_app_ref="",
                 app_path=None,
                 multi_app=True,
-                flwr_dir=None,
+                flwr_dir=str(flwr_dir_),
             )
 
             try:
@@ -169,7 +174,7 @@ def run_clientapp(  # pylint: disable=R0914
 
             # Stop the loop if `flwr-clientapp` is expected to process only a single
             # message
-            if only_once:
+            if run_once:
                 break
 
     except KeyboardInterrupt:

flwr/client/supernode/app.py

@@ -28,6 +28,7 @@ from cryptography.hazmat.primitives.serialization import (
 )
 
 from flwr.common import EventType, event
+from flwr.common.args import try_obtain_root_certificates
 from flwr.common.config import parse_config_args
 from flwr.common.constant import (
     FLEET_API_GRPC_RERE_DEFAULT_ADDRESS,
@@ -61,7 +62,7 @@ def run_supernode() -> None:
             "Ignoring `--flwr-dir`.",
         )
 
-    root_certificates = _get_certificates(args)
+    root_certificates = try_obtain_root_certificates(args, args.superlink)
     load_fn = get_load_client_app_fn(
         default_app_ref="",
         app_path=args.app,
@@ -126,41 +127,6 @@ def _warn_deprecated_server_arg(args: argparse.Namespace) -> None:
             args.superlink = args.server
 
 
-def _get_certificates(args: argparse.Namespace) -> Optional[bytes]:
-    """Load certificates if specified in args."""
-    # Obtain certificates
-    if args.insecure:
-        if args.root_certificates is not None:
-            sys.exit(
-                "Conflicting options: The '--insecure' flag disables HTTPS, "
-                "but '--root-certificates' was also specified. Please remove "
-                "the '--root-certificates' option when running in insecure mode, "
-                "or omit '--insecure' to use HTTPS."
-            )
-        log(
-            WARN,
-            "Option `--insecure` was set. "
-            "Starting insecure HTTP client connected to %s.",
-            args.superlink,
-        )
-        root_certificates = None
-    else:
-        # Load the certificates if provided, or load the system certificates
-        cert_path = args.root_certificates
-        if cert_path is None:
-            root_certificates = None
-        else:
-            root_certificates = Path(cert_path).read_bytes()
-        log(
-            DEBUG,
-            "Starting secure HTTPS client connected to %s "
-            "with the following certificates: %s.",
-            args.superlink,
-            cert_path,
-        )
-    return root_certificates
-
-
 def _parse_args_run_supernode() -> argparse.ArgumentParser:
     """Parse flower-supernode command line arguments."""
     parser = argparse.ArgumentParser(

flwr/common/args.py

@@ -0,0 +1,148 @@
+# 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.
+# ==============================================================================
+"""Common Flower arguments."""
+
+import argparse
+import sys
+from logging import DEBUG, WARN
+from os.path import isfile
+from pathlib import Path
+from typing import Optional
+
+from flwr.common.constant import (
+    TRANSPORT_TYPE_GRPC_ADAPTER,
+    TRANSPORT_TYPE_GRPC_RERE,
+    TRANSPORT_TYPE_REST,
+)
+from flwr.common.logger import log
+
+
+def add_args_flwr_app_common(parser: argparse.ArgumentParser) -> None:
+    """Add common Flower arguments for flwr-*app to the provided parser."""
+    parser.add_argument(
+        "--flwr-dir",
+        default=None,
+        help="""The path containing installed Flower Apps.
+        By default, this value 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
+        """,
+    )
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="Run the server without HTTPS, regardless of whether certificate "
+        "paths are provided. By default, the server runs with HTTPS enabled. "
+        "Use this flag only if you understand the risks.",
+    )
+    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.",
+    )
+
+
+def try_obtain_root_certificates(
+    args: argparse.Namespace,
+    grpc_server_address: str,
+) -> Optional[bytes]:
+    """Validate and return the root certificates."""
+    root_cert_path = args.root_certificates
+    if args.insecure:
+        if root_cert_path is not None:
+            sys.exit(
+                "Conflicting options: The '--insecure' flag disables HTTPS, "
+                "but '--root-certificates' was also specified. Please remove "
+                "the '--root-certificates' option when running in insecure mode, "
+                "or omit '--insecure' to use HTTPS."
+            )
+        log(
+            WARN,
+            "Option `--insecure` was set. Starting insecure HTTP channel to %s.",
+            grpc_server_address,
+        )
+        root_certificates = None
+    else:
+        # Load the certificates if provided, or load the system certificates
+        if not isfile(root_cert_path):
+            sys.exit("Path argument `--root-certificates` does not point to a file.")
+        root_certificates = Path(root_cert_path).read_bytes()
+        log(
+            DEBUG,
+            "Starting secure HTTPS channel to %s "
+            "with the following certificates: %s.",
+            grpc_server_address,
+            root_cert_path,
+        )
+    return root_certificates
+
+
+def try_obtain_server_certificates(
+    args: argparse.Namespace,
+    transport_type: str,
+) -> Optional[tuple[bytes, bytes, bytes]]:
+    """Validate and return the CA cert, server cert, and server private key."""
+    if args.insecure:
+        log(WARN, "Option `--insecure` was set. Starting insecure HTTP server.")
+        return None
+    # Check if certificates are provided
+    if transport_type in [TRANSPORT_TYPE_GRPC_RERE, TRANSPORT_TYPE_GRPC_ADAPTER]:
+        if args.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:
+            if not isfile(args.ssl_ca_certfile):
+                sys.exit("Path argument `--ssl-ca-certfile` does not point to a file.")
+            if not isfile(args.ssl_certfile):
+                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
+            if not isfile(args.ssl_keyfile):
+                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
+            certificates = (
+                Path(args.ssl_ca_certfile).read_bytes(),  # CA certificate
+                Path(args.ssl_certfile).read_bytes(),  # server certificate
+                Path(args.ssl_keyfile).read_bytes(),  # server private key
+            )
+            return certificates
+        if args.ssl_certfile or args.ssl_keyfile or args.ssl_ca_certfile:
+            sys.exit(
+                "You need to provide valid file paths to `--ssl-certfile`, "
+                "`--ssl-keyfile`, and `—-ssl-ca-certfile` to create a secure "
+                "connection in Fleet API server (gRPC-rere)."
+            )
+    if transport_type == TRANSPORT_TYPE_REST:
+        if args.ssl_certfile and args.ssl_keyfile:
+            if not isfile(args.ssl_certfile):
+                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
+            if not isfile(args.ssl_keyfile):
+                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
+            certificates = (
+                b"",
+                Path(args.ssl_certfile).read_bytes(),  # server certificate
+                Path(args.ssl_keyfile).read_bytes(),  # server private key
+            )
+            return certificates
+        if args.ssl_certfile or args.ssl_keyfile:
+            sys.exit(
+                "You need to provide valid file paths to `--ssl-certfile` "
+                "and `--ssl-keyfile` to create a secure connection "
+                "in Fleet API server (REST, experimental)."
+            )
+    sys.exit(
+        "Certificates are required unless running in insecure mode. "
+        "Please provide certificate paths to `--ssl-certfile`, "
+        "`--ssl-keyfile`, and `—-ssl-ca-certfile` or run the server "
+        "in insecure mode using '--insecure' if you understand the risks."
+    )

flwr/common/logger.py

@@ -22,13 +22,14 @@ import time
 from logging import WARN, LogRecord
 from logging.handlers import HTTPHandler
 from queue import Empty, Queue
-from typing import TYPE_CHECKING, Any, Optional, TextIO
+from typing import TYPE_CHECKING, Any, Optional, TextIO, Union
 
 import grpc
 
 from flwr.proto.log_pb2 import PushLogsRequest  # pylint: disable=E0611
 from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
 from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub  # pylint: disable=E0611
+from flwr.proto.simulationio_pb2_grpc import SimulationIoStub  # pylint: disable=E0611
 
 from .constant import LOG_UPLOAD_INTERVAL
 
@@ -346,7 +347,10 @@ def _log_uploader(
 
 
 def start_log_uploader(
-    log_queue: Queue[Optional[str]], node_id: int, run_id: int, stub: ServerAppIoStub
+    log_queue: Queue[Optional[str]],
+    node_id: int,
+    run_id: int,
+    stub: Union[ServerAppIoStub, SimulationIoStub],
 ) -> threading.Thread:
     """Start the log uploader thread and return it."""
     thread = threading.Thread(

flwr/server/app.py

@@ -22,7 +22,6 @@ import sys
 import threading
 from collections.abc import Sequence
 from logging import DEBUG, INFO, WARN
-from os.path import isfile
 from pathlib import Path
 from time import sleep
 from typing import Optional
@@ -37,6 +36,7 @@ from cryptography.hazmat.primitives.serialization import (
 
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH, EventType, event
 from flwr.common.address import parse_address
+from flwr.common.args import try_obtain_server_certificates
 from flwr.common.config import get_flwr_dir, parse_config_args
 from flwr.common.constant import (
     EXEC_API_DEFAULT_ADDRESS,
@@ -215,13 +215,19 @@ def run_superlink() -> None:
 
     event(EventType.RUN_SUPERLINK_ENTER)
 
+    # Warn unused options
+    if args.flwr_dir is not None:
+        log(
+            WARN, "The `--flwr-dir` option is currently not in use and will be ignored."
+        )
+
     # Parse IP addresses
     serverappio_address, _, _ = _format_address(args.serverappio_api_address)
     exec_address, _, _ = _format_address(args.exec_api_address)
     simulationio_address, _, _ = _format_address(args.simulationio_api_address)
 
     # Obtain certificates
-    certificates = _try_obtain_certificates(args)
+    certificates = try_obtain_server_certificates(args, args.fleet_api_type)
 
     # Initialize StateFactory
     state_factory = LinkStateFactory(args.database)
@@ -359,18 +365,23 @@ def run_superlink() -> None:
         else:
             raise ValueError(f"Unknown fleet_api_type: {args.fleet_api_type}")
 
-        if args.isolation == ISOLATION_MODE_SUBPROCESS:
-            # Scheduler thread
-            scheduler_th = threading.Thread(
-                target=_flwr_serverapp_scheduler,
-                args=(
-                    state_factory,
-                    args.serverappio_api_address,
-                    args.ssl_ca_certfile,
-                ),
-            )
-            scheduler_th.start()
-            bckg_threads.append(scheduler_th)
+    if args.isolation == ISOLATION_MODE_SUBPROCESS:
+
+        address = simulationio_address if sim_exec else serverappio_address
+        cmd = "flwr-simulation" if sim_exec else "flwr-serverapp"
+
+        # Scheduler thread
+        scheduler_th = threading.Thread(
+            target=_flwr_scheduler,
+            args=(
+                state_factory,
+                address,
+                args.ssl_ca_certfile,
+                cmd,
+            ),
+        )
+        scheduler_th.start()
+        bckg_threads.append(scheduler_th)
 
     # Graceful shutdown
     register_exit_handlers(
@@ -388,12 +399,13 @@ def run_superlink() -> None:
         exec_server.wait_for_termination(timeout=1)
 
 
-def _flwr_serverapp_scheduler(
+def _flwr_scheduler(
     state_factory: LinkStateFactory,
-    serverappio_api_address: str,
+    io_api_address: str,
     ssl_ca_certfile: Optional[str],
+    cmd: str,
 ) -> None:
-    log(DEBUG, "Started flwr-serverapp scheduler thread.")
+    log(DEBUG, "Started %s scheduler thread.", cmd)
 
     state = state_factory.state()
 
@@ -406,14 +418,16 @@ def _flwr_serverapp_scheduler(
 
             log(
                 INFO,
-                "Launching `flwr-serverapp` subprocess. Connects to SuperLink on %s",
-                serverappio_api_address,
+                "Launching %s subprocess. Connects to SuperLink on %s",
+                cmd,
+                io_api_address,
             )
-            # Start ServerApp subprocess
+            # Start subprocess
             command = [
-                "flwr-serverapp",
+                cmd,
+                "--run-once",
                 "--superlink",
-                serverappio_api_address,
+                io_api_address,
             ]
             if ssl_ca_certfile:
                 command.append("--root-certificates")
@@ -526,60 +540,6 @@ def _try_setup_node_authentication(
         )
 
 
-def _try_obtain_certificates(
-    args: argparse.Namespace,
-) -> Optional[tuple[bytes, bytes, bytes]]:
-    # Obtain certificates
-    if args.insecure:
-        log(WARN, "Option `--insecure` was set. Starting insecure HTTP server.")
-        return None
-    # Check if certificates are provided
-    if args.fleet_api_type in [TRANSPORT_TYPE_GRPC_RERE, TRANSPORT_TYPE_GRPC_ADAPTER]:
-        if args.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:
-            if not isfile(args.ssl_ca_certfile):
-                sys.exit("Path argument `--ssl-ca-certfile` does not point to a file.")
-            if not isfile(args.ssl_certfile):
-                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
-            if not isfile(args.ssl_keyfile):
-                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
-            certificates = (
-                Path(args.ssl_ca_certfile).read_bytes(),  # CA certificate
-                Path(args.ssl_certfile).read_bytes(),  # server certificate
-                Path(args.ssl_keyfile).read_bytes(),  # server private key
-            )
-            return certificates
-        if args.ssl_certfile or args.ssl_keyfile or args.ssl_ca_certfile:
-            sys.exit(
-                "You need to provide valid file paths to `--ssl-certfile`, "
-                "`--ssl-keyfile`, and `—-ssl-ca-certfile` to create a secure "
-                "connection in Fleet API server (gRPC-rere)."
-            )
-    if args.fleet_api_type == TRANSPORT_TYPE_REST:
-        if args.ssl_certfile and args.ssl_keyfile:
-            if not isfile(args.ssl_certfile):
-                sys.exit("Path argument `--ssl-certfile` does not point to a file.")
-            if not isfile(args.ssl_keyfile):
-                sys.exit("Path argument `--ssl-keyfile` does not point to a file.")
-            certificates = (
-                b"",
-                Path(args.ssl_certfile).read_bytes(),  # server certificate
-                Path(args.ssl_keyfile).read_bytes(),  # server private key
-            )
-            return certificates
-        if args.ssl_certfile or args.ssl_keyfile:
-            sys.exit(
-                "You need to provide valid file paths to `--ssl-certfile` "
-                "and `--ssl-keyfile` to create a secure connection "
-                "in Fleet API server (REST, experimental)."
-            )
-    sys.exit(
-        "Certificates are required unless running in insecure mode. "
-        "Please provide certificate paths to `--ssl-certfile`, "
-        "`--ssl-keyfile`, and `—-ssl-ca-certfile` or run the server "
-        "in insecure mode using '--insecure' if you understand the risks."
-    )
-
-
 def _run_fleet_api_grpc_rere(
     address: str,
     state_factory: LinkStateFactory,
@@ -694,6 +654,17 @@ def _add_args_common(parser: argparse.ArgumentParser) -> None:
         "paths are provided. By default, the server runs with HTTPS enabled. "
         "Use this flag only if you understand the risks.",
     )
+    parser.add_argument(
+        "--flwr-dir",
+        default=None,
+        help="""The path containing installed Flower Apps.
+        The default directory is:
+
+        - `$FLWR_HOME/` if `$FLWR_HOME` is defined
+        - `$XDG_DATA_HOME/.flwr/` if `$XDG_DATA_HOME` is defined
+        - `$HOME/.flwr/` in all other cases
+        """,
+    )
     parser.add_argument(
         "--ssl-certfile",
         help="Fleet API server SSL certificate file (as a path str) "