flwr-nightly 1.21.0.dev20250808__tar.gz → 1.21.0.dev20250811__tar.gz

{flwr_nightly-1.21.0.dev20250808 → flwr_nightly-1.21.0.dev20250811}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.21.0.dev20250808
+Version: 1.21.0.dev20250811
 Summary: Flower: A Friendly Federated AI Framework
 License: Apache-2.0
 Keywords: Artificial Intelligence,Federated AI,Federated Analytics,Federated Evaluation,Federated Learning,Flower,Machine Learning

{flwr_nightly-1.21.0.dev20250808 → flwr_nightly-1.21.0.dev20250811}/py/flwr/common/constant.py

@@ -259,3 +259,21 @@ class EventLogWriterType:
     def __new__(cls) -> EventLogWriterType:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class ExecPluginType:
+    """SuperExec plugin types."""
+
+    CLIENT_APP = "clientapp"
+    SERVER_APP = "serverapp"
+    SIMULATION = "simulation"
+
+    def __new__(cls) -> ExecPluginType:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+    @staticmethod
+    def all() -> list[str]:
+        """Return all SuperExec plugin types."""
+        # Filter all constants (uppercase) of the class
+        return [v for k, v in vars(ExecPluginType).items() if k.isupper()]

{flwr_nightly-1.21.0.dev20250808 → flwr_nightly-1.21.0.dev20250811}/py/flwr/common/telemetry.py

@@ -181,6 +181,10 @@ class EventType(str, Enum):
     RUN_SUPERNODE_ENTER = auto()
     RUN_SUPERNODE_LEAVE = auto()
 
+    # CLI: `flower-superexec`
+    RUN_SUPEREXEC_ENTER = auto()
+    RUN_SUPEREXEC_LEAVE = auto()
+
 
 # Use the ThreadPoolExecutor with max_workers=1 to have a queue
 # and also ensure that telemetry calls are not blocking.

{flwr_nightly-1.21.0.dev20250808 → flwr_nightly-1.21.0.dev20250811}/py/flwr/server/serverapp/app.py

@@ -20,7 +20,6 @@ import gc
 from logging import DEBUG, ERROR, INFO
 from pathlib import Path
 from queue import Queue
-from time import sleep
 from typing import Optional
 
 from flwr.cli.config_utils import get_fab_metadata
@@ -64,6 +63,7 @@ from flwr.proto.appio_pb2 import (  # pylint: disable=E0611
 from flwr.proto.run_pb2 import UpdateRunStatusRequest  # pylint: disable=E0611
 from flwr.server.grid.grpc_grid import GrpcGrid
 from flwr.server.run_serverapp import run as run_
+from flwr.supercore.app_utils import simple_get_token, start_parent_process_monitor
 
 
 def flwr_serverapp() -> None:
@@ -91,23 +91,31 @@ def flwr_serverapp() -> None:
     run_serverapp(
         serverappio_api_address=args.serverappio_api_address,
         log_queue=log_queue,
+        token=args.token,
         run_once=args.run_once,
         flwr_dir=args.flwr_dir,
         certificates=None,
+        parent_pid=args.parent_pid,
     )
 
     # Restore stdout/stderr
     restore_output()
 
 
-def run_serverapp(  # pylint: disable=R0914, disable=W0212, disable=R0915
+def run_serverapp(  # pylint: disable=R0913, R0914, R0915, R0917, W0212
     serverappio_api_address: str,
     log_queue: Queue[Optional[str]],
     run_once: bool,
+    token: Optional[str] = None,
     flwr_dir: Optional[str] = None,
     certificates: Optional[bytes] = None,
+    parent_pid: Optional[int] = None,
 ) -> None:
     """Run Flower ServerApp process."""
+    # Monitor the main process in case of SIGKILL
+    if parent_pid is not None:
+        start_parent_process_monitor(parent_pid)
+
     # Resolve directory where FABs are installed
     flwr_dir_ = get_flwr_dir(flwr_dir)
     log_uploader = None
@@ -126,15 +134,15 @@ def run_serverapp(  # pylint: disable=R0914, disable=W0212, disable=R0915
                 root_certificates=certificates,
             )
 
+            # If token is not set, loop until token is received from SuperLink
+            if token is None:
+                log(DEBUG, "[flwr-serverapp] Request token")
+                token = simple_get_token(grid._stub)
+
             # Pull ServerAppInputs from LinkState
-            req = PullAppInputsRequest()
+            req = PullAppInputsRequest(token=token)
             log(DEBUG, "[flwr-serverapp] Pull ServerAppInputs")
             res: PullAppInputsResponse = grid._stub.PullAppInputs(req)
-            if not res.HasField("run"):
-                sleep(3)
-                run_status = None
-                continue
-
             context = context_from_proto(res.context)
             run = run_from_proto(res.run)
             fab = fab_from_proto(res.fab)
@@ -209,7 +217,9 @@ def run_serverapp(  # pylint: disable=R0914, disable=W0212, disable=R0915
             # Send resulting context
             context_proto = context_to_proto(updated_context)
             log(DEBUG, "[flwr-serverapp] Will push ServerAppOutputs")
-            out_req = PushAppOutputsRequest(run_id=run.run_id, context=context_proto)
+            out_req = PushAppOutputsRequest(
+                token=token, run_id=run.run_id, context=context_proto
+            )
             _ = grid._stub.PushAppOutputs(out_req)
 
             run_status = RunStatus(Status.FINISHED, SubStatus.COMPLETED, "")
@@ -250,8 +260,9 @@ def run_serverapp(  # pylint: disable=R0914, disable=W0212, disable=R0915
             if grid:
                 grid.close()
 
-            # Clean up the Context
+            # Clean up the Context and the token
             context = None
+            token = None
             gc.collect()
 
             event(
@@ -276,6 +287,19 @@ def _parse_args_run_flwr_serverapp() -> argparse.ArgumentParser:
         help="Address of SuperLink's ServerAppIo API (IPv4, IPv6, or a domain name)."
         f"By default, it is set to {SERVERAPPIO_API_DEFAULT_CLIENT_ADDRESS}.",
     )
+    parser.add_argument(
+        "--token",
+        type=str,
+        required=False,
+        help="Unique token generated by SuperNode for each ServerApp execution",
+    )
+    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.",
+    )
     parser.add_argument(
         "--run-once",
         action="store_true",

{flwr_nightly-1.21.0.dev20250808 → flwr_nightly-1.21.0.dev20250811}/py/flwr/server/superlink/serverappio/serverappio_servicer.py

@@ -329,14 +329,11 @@ class ServerAppIoServicer(serverappio_pb2_grpc.ServerAppIoServicer):
         # Init access to LinkState
         state = self.state_factory.state()
 
+        # Validate the token
+        run_id = self._verify_token(request.token, context)
+
         # Lock access to LinkState, preventing obtaining the same pending run_id
         with self.lock:
-            # Attempt getting the run_id of a pending run
-            run_id = state.get_pending_run_id()
-            # If there's no pending run, return an empty response
-            if run_id is None:
-                return PullAppInputsResponse()
-
             # Init access to Ffs
             ffs = self.ffs_factory.ffs()
 
@@ -367,6 +364,9 @@ class ServerAppIoServicer(serverappio_pb2_grpc.ServerAppIoServicer):
         """Push ServerApp process outputs."""
         log(DEBUG, "ServerAppIoServicer.PushAppOutputs")
 
+        # Validate the token
+        run_id = self._verify_token(request.token, context)
+
         # Init state and store
         state = self.state_factory.state()
         store = self.objectstore_factory.store()
@@ -381,6 +381,9 @@ class ServerAppIoServicer(serverappio_pb2_grpc.ServerAppIoServicer):
         )
 
         state.set_serverapp_context(request.run_id, context_from_proto(request.context))
+
+        # Remove the token
+        state.delete_token(run_id)
         return PushAppOutputsResponse()
 
     def UpdateRunStatus(
@@ -548,6 +551,18 @@ class ServerAppIoServicer(serverappio_pb2_grpc.ServerAppIoServicer):
 
         return ConfirmMessageReceivedResponse()
 
+    def _verify_token(self, token: str, context: grpc.ServicerContext) -> int:
+        """Verify the token and return the associated run ID."""
+        state = self.state_factory.state()
+        run_id = state.get_run_id_by_token(token)
+        if run_id is None or not state.verify_token(run_id, token):
+            context.abort(
+                grpc.StatusCode.PERMISSION_DENIED,
+                "Invalid token.",
+            )
+            raise RuntimeError("This line should never be reached.")
+        return run_id
+
 
 def _raise_if(validation_error: bool, request_name: str, detail: str) -> None:
     """Raise a `ValueError` with a detailed message if a validation error occurs."""

flwr_nightly-1.21.0.dev20250811/py/flwr/supercore/app_utils.py

@@ -0,0 +1,88 @@
+# 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.
+# ==============================================================================
+"""Utility functions for app processes."""
+
+
+import os
+import signal
+import threading
+import time
+from typing import Union
+
+from flwr.proto.appio_pb2 import (  # pylint: disable=E0611
+    ListAppsToLaunchRequest,
+    ListAppsToLaunchResponse,
+    RequestTokenRequest,
+    RequestTokenResponse,
+)
+from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
+from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub
+
+if os.name == "nt":
+    from ctypes import windll  # type: ignore
+
+
+def _pid_exists(pid: int) -> bool:
+    """Check if a process with the given PID exists.
+
+    This works on Unix-like systems and Windows.
+    """
+    # Use `ctypes` to check if the process exists on Windows
+    if os.name == "nt":
+        handle = windll.kernel32.OpenProcess(0x1000, False, pid)
+        if handle:
+            windll.kernel32.CloseHandle(handle)
+            return True
+        return False
+    # Use `os.kill` on Unix-like systems
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True
+
+
+def start_parent_process_monitor(
+    parent_pid: int,
+) -> None:
+    """Monitor the parent process and exit if it terminates."""
+
+    def monitor() -> None:
+        while True:
+            time.sleep(0.2)
+            if not _pid_exists(parent_pid):
+                # This works on Unix-like systems and Windows
+                # Avoid `os.kill` on Windows
+                signal.raise_signal(signal.SIGTERM)
+
+    threading.Thread(target=monitor, daemon=True).start()
+
+
+def simple_get_token(stub: Union[ClientAppIoStub, ServerAppIoStub]) -> str:
+    """Get a token from SuperLink/SuperNode.
+
+    This shall be removed once the SuperExec is fully implemented.
+    """
+    while True:
+        res: ListAppsToLaunchResponse = stub.ListAppsToLaunch(ListAppsToLaunchRequest())
+
+        for run_id in res.run_ids:
+            tk_res: RequestTokenResponse = stub.RequestToken(
+                RequestTokenRequest(run_id=run_id)
+            )
+            if tk_res.token:
+                return tk_res.token
+
+        time.sleep(1)  # Wait before retrying to get run IDs

flwr_nightly-1.21.0.dev20250811/py/flwr/supercore/cli/__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.
+# ==============================================================================
+"""Flower command line interface for shared infrastructure components."""
+
+
+from .flower_superexec import flower_superexec
+
+__all__ = [
+    "flower_superexec",
+]

flwr_nightly-1.21.0.dev20250811/py/flwr/supercore/cli/flower_superexec.py

@@ -0,0 +1,110 @@
+# 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 flwr.common import EventType, event
+from flwr.common.constant import ExecPluginType
+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.superexec.plugin import (
+    ClientAppExecPlugin,
+    ExecPlugin,
+    ServerAppExecPlugin,
+    SimulationExecPlugin,
+)
+from flwr.supercore.superexec.run_superexec import run_superexec
+
+
+def flower_superexec() -> None:
+    """Run `flower-superexec` command."""
+    args = _parse_args().parse_args()
+
+    # 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})
+
+    # 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,
+        flwr_dir=args.flwr_dir,
+        parent_pid=args.parent_pid,
+    )
+
+
+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(),
+        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.",
+    )
+    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
+    raise ValueError(f"Unknown plugin type: {plugin_type}")

{flwr_nightly-1.21.0.dev20250808 → flwr_nightly-1.21.0.dev20250811}/py/flwr/supercore/superexec/plugin/__init__.py

@@ -17,8 +17,12 @@
 
 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_nightly-1.21.0.dev20250808/py/flwr/supercore/superexec/plugin/clientapp_exec_plugin.py → flwr_nightly-1.21.0.dev20250811/py/flwr/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 SuperExec plugin for ClientApp."""
+"""Simple base Flower SuperExec plugin for app processes."""
 
 
 import os
@@ -23,12 +23,16 @@ from typing import Optional
 from .exec_plugin import ExecPlugin
 
 
-class ClientAppExecPlugin(ExecPlugin):
-    """Simple Flower SuperExec plugin for ClientApp.
+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 ClientAppExecPlugin(ExecPlugin):
 
     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_nightly-1.21.0.dev20250811/py/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_nightly-1.21.0.dev20250811/py/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_nightly-1.21.0.dev20250811/py/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"