flwr-nightly 1.8.0.dev20240314__py3-none-any.whl → 1.11.0.dev20240813__py3-none-any.whl

flwr/superexec/app.py

@@ -0,0 +1,184 @@
+# 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 SuperExec app."""
+
+import argparse
+import sys
+from logging import INFO, WARN
+from pathlib import Path
+from typing import Optional, Tuple
+
+import grpc
+
+from flwr.common import EventType, event, log
+from flwr.common.address import parse_address
+from flwr.common.config import parse_config_args
+from flwr.common.constant import SUPEREXEC_DEFAULT_ADDRESS
+from flwr.common.exit_handlers import register_exit_handlers
+from flwr.common.object_ref import load_app, validate
+
+from .exec_grpc import run_superexec_api_grpc
+from .executor import Executor
+
+
+def run_superexec() -> None:
+    """Run Flower SuperExec."""
+    log(INFO, "Starting Flower SuperExec")
+
+    event(EventType.RUN_SUPEREXEC_ENTER)
+
+    args = _parse_args_run_superexec().parse_args()
+
+    # Parse IP address
+    parsed_address = parse_address(args.address)
+    if not parsed_address:
+        sys.exit(f"SuperExec IP address ({args.address}) cannot be parsed.")
+    host, port, is_v6 = parsed_address
+    address = f"[{host}]:{port}" if is_v6 else f"{host}:{port}"
+
+    # Obtain certificates
+    certificates = _try_obtain_certificates(args)
+
+    # Start SuperExec API
+    superexec_server: grpc.Server = run_superexec_api_grpc(
+        address=address,
+        executor=_load_executor(args),
+        certificates=certificates,
+        config=parse_config_args([args.executor_config]),
+    )
+
+    grpc_servers = [superexec_server]
+
+    # Graceful shutdown
+    register_exit_handlers(
+        event_type=EventType.RUN_SUPEREXEC_LEAVE,
+        grpc_servers=grpc_servers,
+        bckg_threads=None,
+    )
+
+    superexec_server.wait_for_termination()
+
+
+def _parse_args_run_superexec() -> argparse.ArgumentParser:
+    """Parse command line arguments for SuperExec."""
+    parser = argparse.ArgumentParser(
+        description="Start a Flower SuperExec",
+    )
+    parser.add_argument(
+        "--address",
+        help="SuperExec (gRPC) server address (IPv4, IPv6, or a domain name)",
+        default=SUPEREXEC_DEFAULT_ADDRESS,
+    )
+    parser.add_argument(
+        "--executor",
+        help="For example: `deployment:exec` or `project.package.module:wrapper.exec`.",
+        default="flwr.superexec.deployment:executor",
+    )
+    parser.add_argument(
+        "--executor-dir",
+        help="The directory for the executor.",
+        default=".",
+    )
+    parser.add_argument(
+        "--executor-config",
+        help="Key-value pairs for the executor config, separated by commas. "
+        'For example:\n\n`--executor-config superlink="superlink:9091",'
+        'root-certificates="certificates/superlink-ca.crt"`',
+    )
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="Run the SuperExec 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(
+        "--ssl-certfile",
+        help="SuperExec server SSL certificate file (as a path str) "
+        "to create a secure connection.",
+        type=str,
+        default=None,
+    )
+    parser.add_argument(
+        "--ssl-keyfile",
+        help="SuperExec server SSL private key file (as a path str) "
+        "to create a secure connection.",
+        type=str,
+    )
+    parser.add_argument(
+        "--ssl-ca-certfile",
+        help="SuperExec server SSL CA certificate file (as a path str) "
+        "to create a secure connection.",
+        type=str,
+    )
+    return parser
+
+
+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.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:
+        if not Path(args.ssl_ca_certfile).is_file():
+            sys.exit("Path argument `--ssl-ca-certfile` does not point to a file.")
+        if not Path(args.ssl_certfile).is_file():
+            sys.exit("Path argument `--ssl-certfile` does not point to a file.")
+        if not Path(args.ssl_keyfile).is_file():
+            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 SuperExec server (gRPC-rere)."
+        )
+    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 _load_executor(
+    args: argparse.Namespace,
+) -> Executor:
+    """Get the executor plugin."""
+    executor_ref: str = args.executor
+    valid, error_msg = validate(executor_ref, project_dir=args.executor_dir)
+    if not valid and error_msg:
+        raise LoadExecutorError(error_msg) from None
+
+    executor = load_app(executor_ref, LoadExecutorError, args.executor_dir)
+
+    if not isinstance(executor, Executor):
+        raise LoadExecutorError(
+            f"Attribute {executor_ref} is not of type {Executor}",
+        ) from None
+
+    return executor
+
+
+class LoadExecutorError(Exception):
+    """Error when trying to load `Executor`."""

flwr/superexec/deployment.py

@@ -0,0 +1,185 @@
+# 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.
+# ==============================================================================
+"""Deployment engine executor."""
+
+import subprocess
+from logging import ERROR, INFO
+from pathlib import Path
+from typing import Optional
+
+from typing_extensions import override
+
+from flwr.cli.config_utils import get_fab_metadata
+from flwr.cli.install import install_from_fab
+from flwr.common.grpc import create_channel
+from flwr.common.logger import log
+from flwr.common.serde import user_config_to_proto
+from flwr.common.typing import UserConfig
+from flwr.proto.driver_pb2 import CreateRunRequest  # pylint: disable=E0611
+from flwr.proto.driver_pb2_grpc import DriverStub
+from flwr.server.driver.grpc_driver import DEFAULT_SERVER_ADDRESS_DRIVER
+
+from .executor import Executor, RunTracker
+
+
+class DeploymentEngine(Executor):
+    """Deployment engine executor.
+
+    Parameters
+    ----------
+    superlink: str (default: "0.0.0.0:9091")
+        Address of the SuperLink to connect to.
+    root_certificates: Optional[str] (default: None)
+        Specifies the path to the PEM-encoded root certificate file for
+        establishing secure HTTPS connections.
+    flwr_dir: Optional[str] (default: None)
+        The path containing installed Flower Apps.
+    """
+
+    def __init__(
+        self,
+        superlink: str = DEFAULT_SERVER_ADDRESS_DRIVER,
+        root_certificates: Optional[str] = None,
+        flwr_dir: Optional[str] = None,
+    ) -> None:
+        self.superlink = superlink
+        if root_certificates is None:
+            self.root_certificates = None
+            self.root_certificates_bytes = None
+        else:
+            self.root_certificates = root_certificates
+            self.root_certificates_bytes = Path(root_certificates).read_bytes()
+        self.flwr_dir = flwr_dir
+        self.stub: Optional[DriverStub] = None
+
+    @override
+    def set_config(
+        self,
+        config: UserConfig,
+    ) -> None:
+        """Set executor config arguments.
+
+        Parameters
+        ----------
+        config : UserConfig
+            A dictionary for configuration values.
+            Supported configuration key/value pairs:
+            - "superlink": str
+                The address of the SuperLink Driver API.
+            - "root-certificates": str
+                The path to the root certificates.
+            - "flwr-dir": str
+                The path to the Flower directory.
+        """
+        if not config:
+            return
+        if superlink_address := config.get("superlink"):
+            if not isinstance(superlink_address, str):
+                raise ValueError("The `superlink` value should be of type `str`.")
+            self.superlink = superlink_address
+        if root_certificates := config.get("root-certificates"):
+            if not isinstance(root_certificates, str):
+                raise ValueError(
+                    "The `root-certificates` value should be of type `str`."
+                )
+            self.root_certificates = root_certificates
+            self.root_certificates_bytes = Path(str(root_certificates)).read_bytes()
+        if flwr_dir := config.get("flwr-dir"):
+            if not isinstance(flwr_dir, str):
+                raise ValueError("The `flwr-dir` value should be of type `str`.")
+            self.flwr_dir = str(flwr_dir)
+
+    def _connect(self) -> None:
+        if self.stub is not None:
+            return
+        channel = create_channel(
+            server_address=self.superlink,
+            insecure=(self.root_certificates_bytes is None),
+            root_certificates=self.root_certificates_bytes,
+        )
+        self.stub = DriverStub(channel)
+
+    def _create_run(
+        self,
+        fab_id: str,
+        fab_version: str,
+        override_config: UserConfig,
+    ) -> int:
+        if self.stub is None:
+            self._connect()
+
+        assert self.stub is not None
+
+        req = CreateRunRequest(
+            fab_id=fab_id,
+            fab_version=fab_version,
+            override_config=user_config_to_proto(override_config),
+        )
+        res = self.stub.CreateRun(request=req)
+        return int(res.run_id)
+
+    @override
+    def start_run(
+        self,
+        fab_file: bytes,
+        override_config: UserConfig,
+        federation_config: UserConfig,
+    ) -> Optional[RunTracker]:
+        """Start run using the Flower Deployment Engine."""
+        try:
+            # Install FAB to flwr dir
+            fab_version, fab_id = get_fab_metadata(fab_file)
+            install_from_fab(fab_file, None, True)
+
+            # Call SuperLink to create run
+            run_id: int = self._create_run(fab_id, fab_version, override_config)
+            log(INFO, "Created run %s", str(run_id))
+
+            command = [
+                "flower-server-app",
+                "--run-id",
+                str(run_id),
+                "--superlink",
+                str(self.superlink),
+            ]
+
+            if self.flwr_dir:
+                command.append("--flwr-dir")
+                command.append(self.flwr_dir)
+
+            if self.root_certificates is None:
+                command.append("--insecure")
+            else:
+                command.append("--root-certificates")
+                command.append(self.root_certificates)
+
+            # Execute the command
+            proc = subprocess.Popen(  # pylint: disable=consider-using-with
+                command,
+                text=True,
+            )
+            log(INFO, "Started run %s", str(run_id))
+
+            return RunTracker(
+                run_id=run_id,
+                proc=proc,
+            )
+        # pylint: disable-next=broad-except
+        except Exception as e:
+            log(ERROR, "Could not start run: %s", str(e))
+            return None
+
+
+executor = DeploymentEngine()

flwr/superexec/exec_grpc.py

@@ -0,0 +1,55 @@
+# 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.
+# ==============================================================================
+"""SuperExec gRPC API."""
+
+from logging import INFO
+from typing import Optional, Tuple
+
+import grpc
+
+from flwr.common import GRPC_MAX_MESSAGE_LENGTH
+from flwr.common.logger import log
+from flwr.common.typing import UserConfig
+from flwr.proto.exec_pb2_grpc import add_ExecServicer_to_server
+from flwr.server.superlink.fleet.grpc_bidi.grpc_server import generic_create_grpc_server
+
+from .exec_servicer import ExecServicer
+from .executor import Executor
+
+
+def run_superexec_api_grpc(
+    address: str,
+    executor: Executor,
+    certificates: Optional[Tuple[bytes, bytes, bytes]],
+    config: UserConfig,
+) -> grpc.Server:
+    """Run SuperExec API (gRPC, request-response)."""
+    executor.set_config(config)
+
+    exec_servicer: grpc.Server = ExecServicer(
+        executor=executor,
+    )
+    superexec_add_servicer_to_server_fn = add_ExecServicer_to_server
+    superexec_grpc_server = generic_create_grpc_server(
+        servicer_and_add_fn=(exec_servicer, superexec_add_servicer_to_server_fn),
+        server_address=address,
+        max_message_length=GRPC_MAX_MESSAGE_LENGTH,
+        certificates=certificates,
+    )
+
+    log(INFO, "Starting Flower SuperExec gRPC server on %s", address)
+    superexec_grpc_server.start()
+
+    return superexec_grpc_server

flwr/superexec/exec_servicer.py

@@ -0,0 +1,70 @@
+# 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.
+# ==============================================================================
+"""SuperExec API servicer."""
+
+
+from logging import ERROR, INFO
+from typing import Any, Dict, Generator
+
+import grpc
+
+from flwr.common.logger import log
+from flwr.common.serde import user_config_from_proto
+from flwr.proto import exec_pb2_grpc  # pylint: disable=E0611
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    StartRunRequest,
+    StartRunResponse,
+    StreamLogsRequest,
+    StreamLogsResponse,
+)
+
+from .executor import Executor, RunTracker
+
+
+class ExecServicer(exec_pb2_grpc.ExecServicer):
+    """SuperExec API servicer."""
+
+    def __init__(self, executor: Executor) -> None:
+        self.executor = executor
+        self.runs: Dict[int, RunTracker] = {}
+
+    def StartRun(
+        self, request: StartRunRequest, context: grpc.ServicerContext
+    ) -> StartRunResponse:
+        """Create run ID."""
+        log(INFO, "ExecServicer.StartRun")
+
+        run = self.executor.start_run(
+            request.fab_file,
+            user_config_from_proto(request.override_config),
+            user_config_from_proto(request.federation_config),
+        )
+
+        if run is None:
+            log(ERROR, "Executor failed to start run")
+            return StartRunResponse()
+
+        self.runs[run.run_id] = run
+
+        return StartRunResponse(run_id=run.run_id)
+
+    def StreamLogs(
+        self, request: StreamLogsRequest, context: grpc.ServicerContext
+    ) -> Generator[StreamLogsResponse, Any, None]:
+        """Get logs."""
+        logs = ["a", "b", "c"]
+        while context.is_active():
+            for i in range(len(logs)):  # pylint: disable=C0200
+                yield StreamLogsResponse(log_output=logs[i])

flwr/superexec/executor.py

@@ -0,0 +1,75 @@
+# 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.
+# ==============================================================================
+"""Execute and monitor a Flower run."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from subprocess import Popen
+from typing import Optional
+
+from flwr.common.typing import UserConfig
+
+
+@dataclass
+class RunTracker:
+    """Track a Flower run (composed of a run_id and the associated process)."""
+
+    run_id: int
+    proc: Popen  # type: ignore
+
+
+class Executor(ABC):
+    """Execute and monitor a Flower run."""
+
+    @abstractmethod
+    def set_config(
+        self,
+        config: UserConfig,
+    ) -> None:
+        """Register provided config as class attributes.
+
+        Parameters
+        ----------
+        config : UserConfig
+            A dictionary for configuration values.
+        """
+
+    @abstractmethod
+    def start_run(
+        self,
+        fab_file: bytes,
+        override_config: UserConfig,
+        federation_config: UserConfig,
+    ) -> Optional[RunTracker]:
+        """Start a run using the given Flower FAB ID and version.
+
+        This method creates a new run on the SuperLink, returns its run_id
+        and also starts the run execution.
+
+        Parameters
+        ----------
+        fab_file : bytes
+            The Flower App Bundle file bytes.
+        override_config: UserConfig
+            The config overrides dict sent by the user (using `flwr run`).
+        federation_config: UserConfig
+            The federation options dict sent by the user (using `flwr run`).
+
+        Returns
+        -------
+        run_id : Optional[RunTracker]
+            The run_id and the associated process of the run created by the SuperLink,
+            or `None` if it fails.
+        """