flwr 1.20.0__py3-none-any.whl → 1.22.0__py3-none-any.whl

flwr/supercore/cli/flower_superexec.py

@@ -0,0 +1,166 @@
+# 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-superexec` command."""
+
+
+import argparse
+from logging import INFO
+from typing import Any, Optional
+
+import yaml
+
+from flwr.common import EventType, event
+from flwr.common.constant import ExecPluginType
+from flwr.common.exit import ExitCode, flwr_exit
+from flwr.common.logger import log
+from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
+from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub
+from flwr.proto.simulationio_pb2_grpc import SimulationIoStub
+from flwr.supercore.constant import EXEC_PLUGIN_SECTION
+from flwr.supercore.grpc_health import add_args_health
+from flwr.supercore.superexec.plugin import (
+    ClientAppExecPlugin,
+    ExecPlugin,
+    ServerAppExecPlugin,
+    SimulationExecPlugin,
+)
+from flwr.supercore.superexec.run_superexec import run_superexec
+
+try:
+    from flwr.ee import add_ee_args_superexec
+    from flwr.ee.constant import ExecEePluginType
+    from flwr.ee.exec_plugin import get_ee_plugin_and_stub_class
+except ImportError:
+
+    class ExecEePluginType:  # type: ignore[no-redef]
+        """SuperExec EE plugin types."""
+
+        @staticmethod
+        def all() -> list[str]:
+            """Return all SuperExec EE plugin types."""
+            return []
+
+    def get_ee_plugin_and_stub_class(  # pylint: disable=unused-argument
+        plugin_type: str,
+    ) -> Optional[tuple[type[ExecPlugin], type[object]]]:
+        """Get the EE plugin class and stub class based on the plugin type."""
+        return None
+
+    # pylint: disable-next=unused-argument
+    def add_ee_args_superexec(parser: argparse.ArgumentParser) -> None:
+        """Add EE-specific arguments to the parser."""
+
+
+def flower_superexec() -> None:
+    """Run `flower-superexec` command."""
+    args = _parse_args().parse_args()
+    if not args.insecure:
+        flwr_exit(
+            ExitCode.COMMON_TLS_NOT_SUPPORTED,
+            "SuperExec does not support TLS yet.",
+        )
+
+    # Log the first message after parsing arguments in case of `--help`
+    log(INFO, "Starting Flower SuperExec")
+
+    # Trigger telemetry event
+    event(EventType.RUN_SUPEREXEC_ENTER, {"plugin_type": args.plugin_type})
+
+    # Load plugin config from YAML file if provided
+    plugin_config = None
+    if plugin_config_path := getattr(args, "plugin_config", None):
+        try:
+            with open(plugin_config_path, encoding="utf-8") as file:
+                yaml_config: Optional[dict[str, Any]] = yaml.safe_load(file)
+                if yaml_config is None or EXEC_PLUGIN_SECTION not in yaml_config:
+                    raise ValueError(f"Missing '{EXEC_PLUGIN_SECTION}' section.")
+                plugin_config = yaml_config[EXEC_PLUGIN_SECTION]
+        except (FileNotFoundError, yaml.YAMLError, ValueError) as e:
+            flwr_exit(
+                ExitCode.SUPEREXEC_INVALID_PLUGIN_CONFIG,
+                f"Failed to load plugin config from '{plugin_config_path}': {e!r}",
+            )
+
+    # Get the plugin class and stub class based on the plugin type
+    plugin_class, stub_class = _get_plugin_and_stub_class(args.plugin_type)
+    run_superexec(
+        plugin_class=plugin_class,
+        stub_class=stub_class,  # type: ignore
+        appio_api_address=args.appio_api_address,
+        plugin_config=plugin_config,
+        flwr_dir=args.flwr_dir,
+        parent_pid=args.parent_pid,
+        health_server_address=args.health_server_address,
+    )
+
+
+def _parse_args() -> argparse.ArgumentParser:
+    """Parse `flower-superexec` command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Run Flower SuperExec.",
+    )
+    parser.add_argument(
+        "--appio-api-address", type=str, required=True, help="Address of the AppIO API"
+    )
+    parser.add_argument(
+        "--plugin-type",
+        type=str,
+        choices=ExecPluginType.all() + ExecEePluginType.all(),
+        required=True,
+        help="The type of plugin to use.",
+    )
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="Connect to the AppIO API without TLS. "
+        "Data transmitted between the client and server is not encrypted. "
+        "Use this flag only if you understand the risks.",
+    )
+    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(
+        "--parent-pid",
+        type=int,
+        default=None,
+        help="The PID of the parent process. When set, the process will terminate "
+        "when the parent process exits.",
+    )
+    add_ee_args_superexec(parser)
+    add_args_health(parser)
+    return parser
+
+
+def _get_plugin_and_stub_class(
+    plugin_type: str,
+) -> tuple[type[ExecPlugin], type[object]]:
+    """Get the plugin class and stub class based on the plugin type."""
+    if plugin_type == ExecPluginType.CLIENT_APP:
+        return ClientAppExecPlugin, ClientAppIoStub
+    if plugin_type == ExecPluginType.SERVER_APP:
+        return ServerAppExecPlugin, ServerAppIoStub
+    if plugin_type == ExecPluginType.SIMULATION:
+        return SimulationExecPlugin, SimulationIoStub
+    if ret := get_ee_plugin_and_stub_class(plugin_type):
+        return ret  # type: ignore[no-any-return]
+    raise ValueError(f"Unknown plugin type: {plugin_type}")

flwr/supercore/constant.py

@@ -0,0 +1,19 @@
+# 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 Flower infrastructure."""
+
+
+# Top-level key in YAML config for exec plugin settings
+EXEC_PLUGIN_SECTION = "exec_plugin"

flwr/supercore/{scheduler → corestate}/__init__.py

@@ -12,11 +12,11 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower App Scheduler."""
+"""Flower CoreState."""
 
 
-from .plugin import SchedulerPlugin
+from .corestate import CoreState
 
 __all__ = [
-    "SchedulerPlugin",
+    "CoreState",
 ]

flwr/supercore/corestate/corestate.py

@@ -0,0 +1,81 @@
+# 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.
+# ==============================================================================
+"""Abstract base class CoreState."""
+
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class CoreState(ABC):
+    """Abstract base class for core state."""
+
+    @abstractmethod
+    def create_token(self, run_id: int) -> Optional[str]:
+        """Create a token for the given run ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run for which to create a token.
+
+        Returns
+        -------
+        str
+            The newly generated token if one does not already exist
+            for the given run ID, otherwise None.
+        """
+
+    @abstractmethod
+    def verify_token(self, run_id: int, token: str) -> bool:
+        """Verify a token for the given run ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run for which to verify the token.
+        token : str
+            The token to verify.
+
+        Returns
+        -------
+        bool
+            True if the token is valid for the run ID, False otherwise.
+        """
+
+    @abstractmethod
+    def delete_token(self, run_id: int) -> None:
+        """Delete the token for the given run ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run for which to delete the token.
+        """
+
+    @abstractmethod
+    def get_run_id_by_token(self, token: str) -> Optional[int]:
+        """Get the run ID associated with a given token.
+
+        Parameters
+        ----------
+        token : str
+            The token to look up.
+
+        Returns
+        -------
+        Optional[int]
+            The run ID if the token is valid, otherwise None.
+        """

flwr/supercore/grpc_health/__init__.py

@@ -15,8 +15,11 @@
 """GRPC health servicers."""
 
 
+from .health_server import add_args_health, run_health_server_grpc_no_tls
 from .simple_health_servicer import SimpleHealthServicer
 
 __all__ = [
     "SimpleHealthServicer",
+    "add_args_health",
+    "run_health_server_grpc_no_tls",
 ]

flwr/supercore/grpc_health/health_server.py

@@ -0,0 +1,53 @@
+# 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.
+# ==============================================================================
+"""Health servers."""
+
+
+import argparse
+from logging import INFO
+
+import grpc
+from grpc_health.v1.health_pb2_grpc import add_HealthServicer_to_server
+
+from flwr.common.grpc import generic_create_grpc_server
+from flwr.common.logger import log
+
+from .simple_health_servicer import SimpleHealthServicer
+
+
+def run_health_server_grpc_no_tls(address: str) -> grpc.Server:
+    """Run gRPC health server with no TLS."""
+    health_server = generic_create_grpc_server(
+        servicer_and_add_fn=(
+            SimpleHealthServicer(),
+            add_HealthServicer_to_server,
+        ),
+        server_address=address,
+        certificates=None,
+    )
+    log(INFO, "Starting gRPC health server on %s", address)
+    health_server.start()
+    return health_server
+
+
+def add_args_health(parser: argparse.ArgumentParser) -> None:
+    """Add arguments for health server."""
+    parser.add_argument(
+        "--health-server-address",
+        type=str,
+        default=None,
+        help="Health service gRPC server address (IPv4, IPv6, or a domain name) "
+        "with no TLS. If not set, the health server will not be started.",
+    )

flwr/supercore/grpc_health/simple_health_servicer.py

@@ -28,11 +28,11 @@ class SimpleHealthServicer(HealthServicer):  # type: ignore
     """A simple gRPC health servicer that always returns SERVING."""
 
     def Check(
-        self, request: HealthCheckRequest, context: grpc.RpcContext
+        self, request: HealthCheckRequest, context: grpc.ServicerContext
     ) -> HealthCheckResponse:
         """Return a HealthCheckResponse with SERVING status."""
         return HealthCheckResponse(status=HealthCheckResponse.SERVING)
 
-    def Watch(self, request: HealthCheckRequest, context: grpc.RpcContext) -> None:
+    def Watch(self, request: HealthCheckRequest, context: grpc.ServicerContext) -> None:
         """Watch the health status (not implemented)."""
         context.abort(grpc.StatusCode.UNIMPLEMENTED, "Watch is not implemented")

flwr/{superexec → supercore/superexec}/__init__.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower SuperExec service."""
+"""Flower SuperExec."""

flwr/supercore/superexec/plugin/__init__.py

@@ -0,0 +1,28 @@
+# 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 SuperExec plugins."""
+
+
+from .clientapp_exec_plugin import ClientAppExecPlugin
+from .exec_plugin import ExecPlugin
+from .serverapp_exec_plugin import ServerAppExecPlugin
+from .simulation_exec_plugin import SimulationExecPlugin
+
+__all__ = [
+    "ClientAppExecPlugin",
+    "ExecPlugin",
+    "ServerAppExecPlugin",
+    "SimulationExecPlugin",
+]

flwr/{supernode/scheduler/simple_clientapp_scheduler_plugin.py → supercore/superexec/plugin/base_exec_plugin.py}

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Simple Flower ClientApp Scheduler plugin."""
+"""Simple base Flower SuperExec plugin for app processes."""
 
 
 import os
@@ -20,15 +20,19 @@ import subprocess
 from collections.abc import Sequence
 from typing import Optional
 
-from flwr.supercore.scheduler import SchedulerPlugin
+from .exec_plugin import ExecPlugin
 
 
-class SimpleClientAppSchedulerPlugin(SchedulerPlugin):
-    """Simple Flower ClientApp Scheduler plugin.
+class BaseExecPlugin(ExecPlugin):
+    """Simple Flower SuperExec plugin for app processes.
 
     The plugin always selects the first candidate run ID.
     """
 
+    # Placeholders to be defined in subclasses
+    command = ""
+    appio_api_address_arg = ""
+
     def select_run_id(self, candidate_run_ids: Sequence[int]) -> Optional[int]:
         """Select a run ID to execute from a sequence of candidates."""
         if not candidate_run_ids:
@@ -37,8 +41,8 @@ class SimpleClientAppSchedulerPlugin(SchedulerPlugin):
 
     def launch_app(self, token: str, run_id: int) -> None:
         """Launch the application associated with a given run ID and token."""
-        cmds = ["flwr-clientapp", "--insecure"]
-        cmds += ["--clientappio-api-address", self.appio_api_address]
+        cmds = [self.command, "--insecure"]
+        cmds += [self.appio_api_address_arg, self.appio_api_address]
         cmds += ["--token", token]
         cmds += ["--parent-pid", str(os.getpid())]
         cmds += ["--flwr-dir", self.flwr_dir]

flwr/supercore/superexec/plugin/clientapp_exec_plugin.py

@@ -0,0 +1,28 @@
+# 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.
+# ==============================================================================
+"""Simple Flower SuperExec plugin for ClientApp."""
+
+
+from .base_exec_plugin import BaseExecPlugin
+
+
+class ClientAppExecPlugin(BaseExecPlugin):
+    """Simple Flower SuperExec plugin for ClientApp.
+
+    The plugin always selects the first candidate run ID.
+    """
+
+    command = "flwr-clientapp"
+    appio_api_address_arg = "--clientappio-api-address"

flwr/supercore/{scheduler/plugin.py → superexec/plugin/exec_plugin.py}

@@ -12,18 +12,18 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Abstract base class SchedulerPlugin."""
+"""Abstract base class ExecPlugin."""
 
 
 from abc import ABC, abstractmethod
 from collections.abc import Sequence
-from typing import Callable, Optional
+from typing import Any, Callable, Optional
 
 from flwr.common.typing import Run
 
 
-class SchedulerPlugin(ABC):
-    """Abstract base class for Scheduler plugins."""
+class ExecPlugin(ABC):
+    """Abstract base class for SuperExec plugins."""
 
     def __init__(
         self,
@@ -59,7 +59,7 @@ class SchedulerPlugin(ABC):
 
         This method starts the application process using the given `token`.
         The `run_id` is used solely for bookkeeping purposes, allowing any
-        scheduler implementation to associate this launch with a specific run.
+        plugin implementation to associate this launch with a specific run.
 
         Parameters
         ----------
@@ -69,3 +69,13 @@ class SchedulerPlugin(ABC):
            The ID of the run associated with the token, used for tracking or
            logging purposes.
         """
+
+    # This method is optional to implement
+    def load_config(self, yaml_config: dict[str, Any]) -> None:
+        """Load configuration from a YAML dictionary.
+
+        Parameters
+        ----------
+        yaml_config : dict[str, Any]
+            A dictionary representing the YAML configuration.
+        """

flwr/supercore/superexec/plugin/serverapp_exec_plugin.py

@@ -0,0 +1,28 @@
+# 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.
+# ==============================================================================
+"""Simple Flower SuperExec plugin for ServerApp."""
+
+
+from .base_exec_plugin import BaseExecPlugin
+
+
+class ServerAppExecPlugin(BaseExecPlugin):
+    """Simple Flower SuperExec plugin for ServerApp.
+
+    The plugin always selects the first candidate run ID.
+    """
+
+    command = "flwr-serverapp"
+    appio_api_address_arg = "--serverappio-api-address"

flwr/supercore/superexec/plugin/simulation_exec_plugin.py

@@ -0,0 +1,28 @@
+# 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.
+# ==============================================================================
+"""Simple Flower SuperExec plugin for simulation processes."""
+
+
+from .base_exec_plugin import BaseExecPlugin
+
+
+class SimulationExecPlugin(BaseExecPlugin):
+    """Simple Flower SuperExec plugin for simulation processes.
+
+    The plugin always selects the first candidate run ID.
+    """
+
+    command = "flwr-simulation"
+    appio_api_address_arg = "--simulationio-api-address"