flwr-nightly 1.13.0.dev20241019__py3-none-any.whl → 1.13.0.dev20241106__py3-none-any.whl

flwr/superexec/app.py

@@ -16,20 +16,11 @@
 
 import argparse
 import sys
-from logging import INFO, WARN
-from pathlib import Path
-from typing import Optional
+from logging import INFO
 
-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 EXEC_API_DEFAULT_ADDRESS
-from flwr.common.exit_handlers import register_exit_handlers
+from flwr.common import log
 from flwr.common.object_ref import load_app, validate
 
-from .exec_grpc import run_superexec_api_grpc
 from .executor import Executor
 
 
@@ -37,133 +28,14 @@ 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] if args.executor_config else 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=EXEC_API_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 spaces. "
-        '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."
+        "Manually launching the SuperExec is deprecated. Since `flwr 1.13.0` "
+        "the executor service runs in the SuperLink. Launching it manually is not "
+        "recommended."
     )
 
 
-def _load_executor(
+def load_executor(
     args: argparse.Namespace,
 ) -> Executor:
     """Get the executor plugin."""

flwr/superexec/deployment.py

@@ -15,23 +15,21 @@
 """Deployment engine executor."""
 
 import hashlib
-import subprocess
 from logging import ERROR, INFO
 from pathlib import Path
 from typing import Optional
 
 from typing_extensions import override
 
-from flwr.cli.install import install_from_fab
-from flwr.common.constant import DRIVER_API_DEFAULT_ADDRESS
-from flwr.common.grpc import create_channel
+from flwr.common import ConfigsRecord, Context, RecordSet
+from flwr.common.constant import SERVERAPPIO_API_DEFAULT_ADDRESS, Status, SubStatus
 from flwr.common.logger import log
-from flwr.common.serde import fab_to_proto, user_config_to_proto
-from flwr.common.typing import Fab, UserConfig
-from flwr.proto.driver_pb2_grpc import DriverStub
-from flwr.proto.run_pb2 import CreateRunRequest  # pylint: disable=E0611
+from flwr.common.typing import Fab, RunStatus, UserConfig
+from flwr.server.superlink.ffs import Ffs
+from flwr.server.superlink.ffs.ffs_factory import FfsFactory
+from flwr.server.superlink.linkstate import LinkState, LinkStateFactory
 
-from .executor import Executor, RunTracker
+from .executor import Executor
 
 
 class DeploymentEngine(Executor):
@@ -50,7 +48,7 @@ class DeploymentEngine(Executor):
 
     def __init__(
         self,
-        superlink: str = DRIVER_API_DEFAULT_ADDRESS,
+        superlink: str = SERVERAPPIO_API_DEFAULT_ADDRESS,
         root_certificates: Optional[str] = None,
         flwr_dir: Optional[str] = None,
     ) -> None:
@@ -62,7 +60,30 @@ class DeploymentEngine(Executor):
             self.root_certificates = root_certificates
             self.root_certificates_bytes = Path(root_certificates).read_bytes()
         self.flwr_dir = flwr_dir
-        self.stub: Optional[DriverStub] = None
+        self.linkstate_factory: Optional[LinkStateFactory] = None
+        self.ffs_factory: Optional[FfsFactory] = None
+
+    @override
+    def initialize(
+        self, linkstate_factory: LinkStateFactory, ffs_factory: FfsFactory
+    ) -> None:
+        """Initialize the executor with the necessary factories."""
+        self.linkstate_factory = linkstate_factory
+        self.ffs_factory = ffs_factory
+
+    @property
+    def linkstate(self) -> LinkState:
+        """Return the LinkState."""
+        if self.linkstate_factory is None:
+            raise RuntimeError("Executor is not initialized.")
+        return self.linkstate_factory.state()
+
+    @property
+    def ffs(self) -> Ffs:
+        """Return the Flower File Storage (FFS)."""
+        if self.ffs_factory is None:
+            raise RuntimeError("Executor is not initialized.")
+        return self.ffs_factory.ffs()
 
     @override
     def set_config(
@@ -77,7 +98,7 @@ class DeploymentEngine(Executor):
             A dictionary for configuration values.
             Supported configuration key/value pairs:
             - "superlink": str
-                The address of the SuperLink Driver API.
+                The address of the SuperLink ServerAppIo API.
             - "root-certificates": str
                 The path to the root certificates.
             - "flwr-dir": str
@@ -101,32 +122,31 @@ class DeploymentEngine(Executor):
                 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: Fab,
         override_config: UserConfig,
     ) -> int:
-        if self.stub is None:
-            self._connect()
+        fab_hash = self.ffs.put(fab.content, {})
+        if fab_hash != fab.hash_str:
+            raise RuntimeError(
+                f"FAB ({fab.hash_str}) hash from request doesn't match contents"
+            )
 
-        assert self.stub is not None
+        run_id = self.linkstate.create_run(
+            None, None, fab_hash, override_config, ConfigsRecord()
+        )
+        return run_id
 
-        req = CreateRunRequest(
-            fab=fab_to_proto(fab),
-            override_config=user_config_to_proto(override_config),
+    def _create_context(self, run_id: int) -> None:
+        """Register a Context for a Run."""
+        # Create an empty context for the Run
+        context = Context(
+            run_id=run_id, node_id=0, node_config={}, state=RecordSet(), run_config={}
         )
-        res = self.stub.CreateRun(request=req)
-        return int(res.run_id)
+
+        # Register the context at the LinkState
+        self.linkstate.set_serverapp_context(run_id=run_id, context=context)
 
     @override
     def start_run(
@@ -134,52 +154,27 @@ class DeploymentEngine(Executor):
         fab_file: bytes,
         override_config: UserConfig,
         federation_config: UserConfig,
-    ) -> Optional[RunTracker]:
+    ) -> Optional[int]:
         """Start run using the Flower Deployment Engine."""
+        run_id = None
         try:
-            # Install FAB to flwr dir
-            install_from_fab(fab_file, None, True)
 
             # Call SuperLink to create run
-            run_id: int = self._create_run(
+            run_id = self._create_run(
                 Fab(hashlib.sha256(fab_file).hexdigest(), fab_file), 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,
-                stdout=subprocess.PIPE,
-                stderr=subprocess.PIPE,
-                text=True,
-            )
-            log(INFO, "Started run %s", str(run_id))
+            # Register context for the Run
+            self._create_context(run_id=run_id)
+            log(INFO, "Created run %s", str(run_id))
 
-            return RunTracker(
-                run_id=run_id,
-                proc=proc,
-            )
+            return run_id
         # pylint: disable-next=broad-except
         except Exception as e:
             log(ERROR, "Could not start run: %s", str(e))
+            if run_id:
+                run_status = RunStatus(Status.FINISHED, SubStatus.FAILED, str(e))
+                self.linkstate.update_run_status(run_id, new_status=run_status)
             return None
 
 

flwr/superexec/exec_grpc.py

@@ -23,33 +23,40 @@ 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.ffs.ffs_factory import FfsFactory
 from flwr.server.superlink.fleet.grpc_bidi.grpc_server import generic_create_grpc_server
+from flwr.server.superlink.linkstate import LinkStateFactory
 
 from .exec_servicer import ExecServicer
 from .executor import Executor
 
 
-def run_superexec_api_grpc(
+# pylint: disable-next=too-many-arguments, too-many-positional-arguments
+def run_exec_api_grpc(
     address: str,
     executor: Executor,
+    state_factory: LinkStateFactory,
+    ffs_factory: FfsFactory,
     certificates: Optional[tuple[bytes, bytes, bytes]],
     config: UserConfig,
 ) -> grpc.Server:
-    """Run SuperExec API (gRPC, request-response)."""
+    """Run Exec API (gRPC, request-response)."""
     executor.set_config(config)
 
     exec_servicer: grpc.Server = ExecServicer(
+        linkstate_factory=state_factory,
+        ffs_factory=ffs_factory,
         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),
+    exec_add_servicer_to_server_fn = add_ExecServicer_to_server
+    exec_grpc_server = generic_create_grpc_server(
+        servicer_and_add_fn=(exec_servicer, exec_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()
+    log(INFO, "Flower Deployment Engine: Starting Exec API on %s", address)
+    exec_grpc_server.start()
 
-    return superexec_grpc_server
+    return exec_grpc_server

flwr/superexec/exec_servicer.py

@@ -15,9 +15,6 @@
 """SuperExec API servicer."""
 
 
-import select
-import sys
-import threading
 import time
 from collections.abc import Generator
 from logging import ERROR, INFO
@@ -25,6 +22,7 @@ from typing import Any
 
 import grpc
 
+from flwr.common.constant import LOG_STREAM_INTERVAL, Status
 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
@@ -34,18 +32,25 @@ from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
     StreamLogsRequest,
     StreamLogsResponse,
 )
+from flwr.server.superlink.ffs.ffs_factory import FfsFactory
+from flwr.server.superlink.linkstate import LinkStateFactory
 
-from .executor import Executor, RunTracker
-
-SELECT_TIMEOUT = 1  # Timeout for selecting ready-to-read file descriptors (in seconds)
+from .executor import Executor
 
 
 class ExecServicer(exec_pb2_grpc.ExecServicer):
     """SuperExec API servicer."""
 
-    def __init__(self, executor: Executor) -> None:
+    def __init__(
+        self,
+        linkstate_factory: LinkStateFactory,
+        ffs_factory: FfsFactory,
+        executor: Executor,
+    ) -> None:
+        self.linkstate_factory = linkstate_factory
+        self.ffs_factory = ffs_factory
         self.executor = executor
-        self.runs: dict[int, RunTracker] = {}
+        self.executor.initialize(linkstate_factory, ffs_factory)
 
     def StartRun(
         self, request: StartRunRequest, context: grpc.ServicerContext
@@ -53,84 +58,50 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         """Create run ID."""
         log(INFO, "ExecServicer.StartRun")
 
-        run = self.executor.start_run(
+        run_id = self.executor.start_run(
             request.fab.content,
             user_config_from_proto(request.override_config),
             user_config_from_proto(request.federation_config),
         )
 
-        if run is None:
+        if run_id is None:
             log(ERROR, "Executor failed to start run")
             return StartRunResponse()
 
-        self.runs[run.run_id] = run
-
-        # Start a background thread to capture the log output
-        capture_thread = threading.Thread(
-            target=_capture_logs, args=(run,), daemon=True
-        )
-        capture_thread.start()
-
-        return StartRunResponse(run_id=run.run_id)
+        return StartRunResponse(run_id=run_id)
 
     def StreamLogs(  # pylint: disable=C0103
         self, request: StreamLogsRequest, context: grpc.ServicerContext
     ) -> Generator[StreamLogsResponse, Any, None]:
         """Get logs."""
         log(INFO, "ExecServicer.StreamLogs")
+        state = self.linkstate_factory.state()
+
+        # Retrieve run ID
+        run_id = request.run_id
 
         # Exit if `run_id` not found
-        if request.run_id not in self.runs:
+        if not state.get_run(run_id):
             context.abort(grpc.StatusCode.NOT_FOUND, "Run ID not found")
 
-        last_sent_index = 0
+        after_timestamp = request.after_timestamp + 1e-6
         while context.is_active():
-            # Yield n'th row of logs, if n'th row < len(logs)
-            logs = self.runs[request.run_id].logs
-            for i in range(last_sent_index, len(logs)):
-                yield StreamLogsResponse(log_output=logs[i])
-            last_sent_index = len(logs)
+            log_msg, latest_timestamp = state.get_serverapp_log(run_id, after_timestamp)
+            if log_msg:
+                yield StreamLogsResponse(
+                    log_output=log_msg,
+                    latest_timestamp=latest_timestamp,
+                )
+                # Add a small epsilon to the latest timestamp to avoid getting
+                # the same log
+                after_timestamp = max(latest_timestamp + 1e-6, after_timestamp)
 
             # Wait for and continue to yield more log responses only if the
             # run isn't completed yet. If the run is finished, the entire log
             # is returned at this point and the server ends the stream.
-            if self.runs[request.run_id].proc.poll() is not None:
+            run_status = state.get_run_status({run_id})[run_id]
+            if run_status.status == Status.FINISHED:
                 log(INFO, "All logs for run ID `%s` returned", request.run_id)
-                context.set_code(grpc.StatusCode.OK)
                 context.cancel()
 
-            time.sleep(1.0)  # Sleep briefly to avoid busy waiting
-
-
-def _capture_logs(
-    run: RunTracker,
-) -> None:
-    while True:
-        # Explicitly check if Popen.poll() is None. Required for `pytest`.
-        if run.proc.poll() is None:
-            # Select streams only when ready to read
-            ready_to_read, _, _ = select.select(
-                [run.proc.stdout, run.proc.stderr],
-                [],
-                [],
-                SELECT_TIMEOUT,
-            )
-            # Read from std* and append to RunTracker.logs
-            for stream in ready_to_read:
-                # Flush stdout to view output in real time
-                readline = stream.readline()
-                sys.stdout.write(readline)
-                sys.stdout.flush()
-                # Append to logs
-                line = readline.rstrip()
-                if line:
-                    run.logs.append(f"{line}")
-
-        # Close std* to prevent blocking
-        elif run.proc.poll() is not None:
-            log(INFO, "Subprocess finished, exiting log capture")
-            if run.proc.stdout:
-                run.proc.stdout.close()
-            if run.proc.stderr:
-                run.proc.stderr.close()
-            break
+            time.sleep(LOG_STREAM_INTERVAL)  # Sleep briefly to avoid busy waiting

flwr/superexec/executor.py

@@ -20,6 +20,8 @@ from subprocess import Popen
 from typing import Optional
 
 from flwr.common.typing import UserConfig
+from flwr.server.superlink.ffs.ffs_factory import FfsFactory
+from flwr.server.superlink.linkstate import LinkStateFactory
 
 
 @dataclass
@@ -34,6 +36,23 @@ class RunTracker:
 class Executor(ABC):
     """Execute and monitor a Flower run."""
 
+    @abstractmethod
+    def initialize(
+        self, linkstate_factory: LinkStateFactory, ffs_factory: FfsFactory
+    ) -> None:
+        """Initialize the executor with the necessary factories.
+
+        This method sets up the executor by providing it with the factories required
+        to access the LinkState and the Flower File Storage (FFS) in the SuperLink.
+
+        Parameters
+        ----------
+        linkstate_factory : LinkStateFactory
+            The factory to create access to the LinkState.
+        ffs_factory : FfsFactory
+            The factory to create access to the Flower File Storage (FFS).
+        """
+
     @abstractmethod
     def set_config(
         self,
@@ -53,7 +72,7 @@ class Executor(ABC):
         fab_file: bytes,
         override_config: UserConfig,
         federation_config: UserConfig,
-    ) -> Optional[RunTracker]:
+    ) -> Optional[int]:
         """Start a run using the given Flower FAB ID and version.
 
         This method creates a new run on the SuperLink, returns its run_id
@@ -70,7 +89,6 @@ class Executor(ABC):
 
         Returns
         -------
-        run_id : Optional[RunTracker]
-            The run_id and the associated process of the run created by the SuperLink,
-            or `None` if it fails.
+        run_id : Optional[int]
+            The run_id of the run created by the SuperLink, or `None` if it fails.
         """

flwr/superexec/simulation.py

@@ -29,9 +29,11 @@ from flwr.common.config import unflatten_dict
 from flwr.common.constant import RUN_ID_NUM_BYTES
 from flwr.common.logger import log
 from flwr.common.typing import UserConfig
-from flwr.server.superlink.state.utils import generate_rand_int_from_bytes
+from flwr.server.superlink.ffs.ffs_factory import FfsFactory
+from flwr.server.superlink.linkstate import LinkStateFactory
+from flwr.server.superlink.linkstate.utils import generate_rand_int_from_bytes
 
-from .executor import Executor, RunTracker
+from .executor import Executor
 
 
 def _user_config_to_str(user_config: UserConfig) -> str:
@@ -70,6 +72,12 @@ class SimulationEngine(Executor):
         self.num_supernodes = num_supernodes
         self.verbose = verbose
 
+    @override
+    def initialize(
+        self, linkstate_factory: LinkStateFactory, ffs_factory: FfsFactory
+    ) -> None:
+        """Initialize the executor with the necessary factories."""
+
     @override
     def set_config(
         self,
@@ -117,7 +125,7 @@ class SimulationEngine(Executor):
         fab_file: bytes,
         override_config: UserConfig,
         federation_config: UserConfig,
-    ) -> Optional[RunTracker]:
+    ) -> Optional[int]:
         """Start run using the Flower Simulation Engine."""
         if self.num_supernodes is None:
             raise ValueError(
@@ -191,17 +199,14 @@ class SimulationEngine(Executor):
                 command.extend(["--run-config", f"{override_config_str}"])
 
             # Start Simulation
-            proc = subprocess.Popen(  # pylint: disable=consider-using-with
+            _ = 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,
-            )
+            return run_id
 
         # pylint: disable-next=broad-except
         except Exception as e:

{flwr_nightly-1.13.0.dev20241019.dist-info → flwr_nightly-1.13.0.dev20241106.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: flwr-nightly
-Version: 1.13.0.dev20241019
+Version: 1.13.0.dev20241106
 Summary: Flower: A Friendly Federated Learning Framework
 Home-page: https://flower.ai
 License: Apache-2.0