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

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,7 +12,7 @@
 # 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
@@ -22,8 +22,8 @@ from typing import 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
         ----------

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"

flwr/supercore/superexec/run_superexec.py

@@ -0,0 +1,185 @@
+# 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."""
+
+
+import time
+from logging import WARN
+from typing import Optional, Union
+
+from flwr.common.config import get_flwr_dir
+from flwr.common.exit import register_signal_handlers
+from flwr.common.grpc import create_channel, on_channel_state_change
+from flwr.common.logger import log
+from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
+from flwr.common.serde import run_from_proto
+from flwr.common.telemetry import EventType
+from flwr.common.typing import Run
+from flwr.proto.appio_pb2 import (  # pylint: disable=E0611
+    ListAppsToLaunchRequest,
+    RequestTokenRequest,
+)
+from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
+from flwr.proto.run_pb2 import GetRunRequest  # pylint: disable=E0611
+from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub
+from flwr.proto.simulationio_pb2_grpc import SimulationIoStub
+from flwr.supercore.app_utils import start_parent_process_monitor
+from flwr.supercore.grpc_health import run_health_server_grpc_no_tls
+
+from .plugin import ExecPlugin
+
+
+def run_superexec(  # pylint: disable=R0913,R0914,R0917
+    plugin_class: type[ExecPlugin],
+    stub_class: Union[
+        type[ClientAppIoStub], type[ServerAppIoStub], type[SimulationIoStub]
+    ],
+    appio_api_address: str,
+    flwr_dir: Optional[str] = None,
+    parent_pid: Optional[int] = None,
+    health_server_address: Optional[str] = None,
+) -> None:
+    """Run Flower SuperExec.
+
+    Parameters
+    ----------
+    plugin_class : type[ExecPlugin]
+        The class of the SuperExec plugin to use.
+    stub_class : type[ClientAppIoStub]
+        The gRPC stub class for the AppIO API.
+    appio_api_address : str
+        The address of the AppIO API.
+    flwr_dir : Optional[str] (default: None)
+        The Flower directory.
+    parent_pid : Optional[int] (default: None)
+        The PID of the parent process. If provided, the SuperExec will terminate
+        when the parent process exits.
+    health_server_address : Optional[str] (default: None)
+        The address of the health server. If `None` is provided, the health server will
+        NOT be started.
+    """
+    # Start monitoring the parent process if a PID is provided
+    if parent_pid is not None:
+        start_parent_process_monitor(parent_pid)
+
+    # Launch gRPC health server
+    grpc_servers = []
+    if health_server_address is not None:
+        health_server = run_health_server_grpc_no_tls(health_server_address)
+        grpc_servers.append(health_server)
+
+    # Create the channel to the AppIO API
+    # No TLS support for now, so insecure connection
+    channel = create_channel(
+        server_address=appio_api_address,
+        insecure=True,
+        root_certificates=None,
+    )
+    channel.subscribe(on_channel_state_change)
+
+    # Register exit handlers to close the channel on exit
+    register_signal_handlers(
+        event_type=EventType.RUN_SUPEREXEC_LEAVE,
+        exit_message="SuperExec terminated gracefully.",
+        grpc_servers=grpc_servers,
+        exit_handlers=[lambda: channel.close()],  # pylint: disable=W0108
+    )
+
+    # Create the gRPC stub for the AppIO API
+    stub = stub_class(channel)
+    _wrap_stub(stub, _make_simple_grpc_retry_invoker())
+
+    def get_run(run_id: int) -> Run:
+        _req = GetRunRequest(run_id=run_id)
+        _res = stub.GetRun(_req)
+        return run_from_proto(_res.run)
+
+    # Create the SuperExec plugin instance
+    plugin = plugin_class(
+        appio_api_address=appio_api_address,
+        flwr_dir=str(get_flwr_dir(flwr_dir)),
+        get_run=get_run,
+    )
+
+    # Start the main loop
+    try:
+        while True:
+            # Fetch suitable run IDs
+            ls_req = ListAppsToLaunchRequest()
+            ls_res = stub.ListAppsToLaunch(ls_req)
+
+            # Allow the plugin to select a run ID
+            run_id = None
+            if ls_res.run_ids:
+                run_id = plugin.select_run_id(candidate_run_ids=ls_res.run_ids)
+
+            # Apply for a token if a run ID was selected
+            if run_id is not None:
+                tk_req = RequestTokenRequest(run_id=run_id)
+                tk_res = stub.RequestToken(tk_req)
+
+                # Launch the app if a token was granted; do nothing if not
+                if tk_res.token:
+                    plugin.launch_app(token=tk_res.token, run_id=run_id)
+
+            # Sleep for a while before checking again
+            time.sleep(1)
+    finally:
+        channel.close()
+
+
+def run_with_deprecation_warning(  # pylint: disable=R0913, R0917
+    cmd: str,
+    plugin_type: str,
+    plugin_class: type[ExecPlugin],
+    stub_class: Union[
+        type[ClientAppIoStub], type[ServerAppIoStub], type[SimulationIoStub]
+    ],
+    appio_api_address: str,
+    flwr_dir: Optional[str],
+    parent_pid: Optional[int],
+    warn_run_once: bool,
+) -> None:
+    """Log a deprecation warning and run the equivalent `flower-superexec` command.
+
+    Used for legacy long-running `flwr-*` commands (i.e., without `--token`) that will
+    be removed in favor of `flower-superexec`.
+    """
+    log(
+        WARN,
+        "Directly executing `%s` is DEPRECATED and will be prohibited "
+        "in a future release. Please use `flower-superexec` instead.",
+        cmd,
+    )
+    log(WARN, "For now, the following command is being run automatically:")
+    new_cmd = f"flower-superexec --insecure --plugin-type {plugin_type} "
+    new_cmd += f"--appio-api-address {appio_api_address} "
+    if flwr_dir is not None:
+        new_cmd += f"--flwr-dir {flwr_dir} "
+    if parent_pid is not None:
+        new_cmd += f"--parent-pid {parent_pid}"
+    log(WARN, new_cmd)
+
+    # Warn about unsupported `--run-once` flag
+    if warn_run_once:
+        log(WARN, "`flower-superexec` does not support the `--run-once` flag.")
+
+    run_superexec(
+        plugin_class=plugin_class,
+        stub_class=stub_class,
+        appio_api_address=appio_api_address,
+        flwr_dir=flwr_dir,
+        parent_pid=parent_pid,
+    )

flwr/superlink/servicer/__init__.py

@@ -0,0 +1,15 @@
+# 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 SuperLink servicers."""

flwr/superlink/servicer/control/__init__.py

@@ -0,0 +1,22 @@
+# 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.
+# ==============================================================================
+"""Control API Servicer."""
+
+
+from .control_grpc import run_control_api_grpc
+
+__all__ = [
+    "run_control_api_grpc",
+]

flwr/{superexec/exec_event_log_interceptor.py → superlink/servicer/control/control_event_log_interceptor.py}

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower Exec API event log interceptor."""
+"""Flower Control API event log interceptor."""
 
 
 from collections.abc import Iterator
@@ -24,11 +24,11 @@ from google.protobuf.message import Message as GrpcMessage
 from flwr.common.event_log_plugin.event_log_plugin import EventLogWriterPlugin
 from flwr.common.typing import LogEntry
 
-from .exec_user_auth_interceptor import shared_account_info
+from .control_user_auth_interceptor import shared_account_info
 
 
-class ExecEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
-    """Exec API interceptor for logging events."""
+class ControlEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
+    """Control API interceptor for logging events."""
 
     def __init__(self, log_plugin: EventLogWriterPlugin) -> None:
         self.log_plugin = log_plugin
@@ -44,12 +44,12 @@ class ExecEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
         Continue RPC call if event logger is enabled on the SuperLink, else, terminate
         RPC call by setting context to abort.
         """
-        # Only apply to Exec service
-        if not handler_call_details.method.startswith("/flwr.proto.Exec/"):
+        # Only apply to Control service
+        if not handler_call_details.method.startswith("/flwr.proto.Control/"):
             return continuation(handler_call_details)
 
         # One of the method handlers in
-        # `flwr.superexec.exec_servicer.ExecServicer`
+        # `flwr.superlink.servicer.control.ControlServicer`
         method_handler: grpc.RpcMethodHandler = continuation(handler_call_details)
         method_name: str = handler_call_details.method
         return self._generic_event_log_unary_method_handler(method_handler, method_name)