flwr-nightly 1.21.0.dev20250807__py3-none-any.whl → 1.21.0.dev20250809__py3-none-any.whl

flwr/common/constant.py

@@ -259,3 +259,19 @@ class EventLogWriterType:
     def __new__(cls) -> EventLogWriterType:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class ExecPluginType:
+    """SuperExec plugin types."""
+
+    CLIENT_APP = "clientapp"
+
+    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/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/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/server/superlink/linkstate/in_memory_linkstate.py

@@ -686,12 +686,12 @@ class InMemoryLinkState(LinkState):  # pylint: disable=R0902,R0904
             latest_timestamp = run.logs[-1][0] if index < len(run.logs) else 0.0
             return "".join(log for _, log in run.logs[index:]), latest_timestamp
 
-    def create_token(self, run_id: int) -> str:
+    def create_token(self, run_id: int) -> Optional[str]:
         """Create a token for the given run ID."""
         token = secrets.token_hex(FLWR_APP_TOKEN_LENGTH)  # Generate a random token
         with self.lock_token_store:
             if run_id in self.token_store:
-                raise ValueError("Token already created for this run ID")
+                return None  # Token already created for this run ID
             self.token_store[run_id] = token
             self.token_to_run_id[token] = run_id
         return token

flwr/server/superlink/linkstate/sqlite_linkstate.py

@@ -1148,7 +1148,7 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
 
         return message_ins
 
-    def create_token(self, run_id: int) -> str:
+    def create_token(self, run_id: int) -> Optional[str]:
         """Create a token for the given run ID."""
         token = secrets.token_hex(FLWR_APP_TOKEN_LENGTH)  # Generate a random token
         query = "INSERT INTO token_store (run_id, token) VALUES (:run_id, :token);"
@@ -1156,7 +1156,7 @@ class SqliteLinkState(LinkState):  # pylint: disable=R0904
         try:
             self.query(query, data)
         except sqlite3.IntegrityError:
-            raise ValueError("Token already created for this run ID") from None
+            return None  # Token already created for this run ID
         return token
 
     def verify_token(self, run_id: int, token: str) -> bool:

flwr/server/superlink/serverappio/serverappio_servicer.py

@@ -114,21 +114,35 @@ class ServerAppIoServicer(serverappio_pb2_grpc.ServerAppIoServicer):
         context: grpc.ServicerContext,
     ) -> ListAppsToLaunchResponse:
         """Get run IDs with pending messages."""
-        log(DEBUG, "ClientAppIo.ListAppsToLaunch")
+        log(DEBUG, "ServerAppIoServicer.ListAppsToLaunch")
 
-        context.abort(
-            grpc.StatusCode.UNIMPLEMENTED, "ListAppsToLaunch is not implemented"
-        )
-        raise NotImplementedError
+        # Initialize state connection
+        state = self.state_factory.state()
+
+        # Get IDs of runs in pending status
+        run_ids = state.get_run_ids(flwr_aid=None)
+        pending_run_ids = []
+        for run_id, status in state.get_run_status(run_ids).items():
+            if status.status == Status.PENDING:
+                pending_run_ids.append(run_id)
+
+        # Return run IDs
+        return ListAppsToLaunchResponse(run_ids=pending_run_ids)
 
     def RequestToken(
         self, request: RequestTokenRequest, context: grpc.ServicerContext
     ) -> RequestTokenResponse:
         """Request token."""
-        log(DEBUG, "ClientAppIo.RequestToken")
+        log(DEBUG, "ServerAppIoServicer.RequestToken")
+
+        # Initialize state connection
+        state = self.state_factory.state()
+
+        # Attempt to create a token for the provided run ID
+        token = state.create_token(request.run_id)
 
-        context.abort(grpc.StatusCode.UNIMPLEMENTED, "RequestToken is not implemented")
-        raise NotImplementedError
+        # Return the token
+        return RequestTokenResponse(token=token or "")
 
     def GetNodes(
         self, request: GetNodesRequest, context: grpc.ServicerContext
@@ -315,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()
 
@@ -353,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()
@@ -367,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(
@@ -534,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/supercore/app_utils.py

@@ -0,0 +1,62 @@
+# 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 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
+
+
+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 os.getppid() != parent_pid:
+                os.kill(os.getpid(), 9)
+
+    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/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/supercore/cli/flower_superexec.py

@@ -0,0 +1,91 @@
+# 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.supercore.superexec.plugin import ClientAppExecPlugin, ExecPlugin
+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,
+    )
+
+
+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
+        """,
+    )
+    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
+    raise ValueError(f"Unknown plugin type: {plugin_type}")

flwr/supercore/corestate/corestate.py

@@ -23,7 +23,7 @@ class CoreState(ABC):
     """Abstract base class for core state."""
 
     @abstractmethod
-    def create_token(self, run_id: int) -> str:
+    def create_token(self, run_id: int) -> Optional[str]:
         """Create a token for the given run ID.
 
         Parameters
@@ -34,7 +34,8 @@ class CoreState(ABC):
         Returns
         -------
         str
-            A unique token associated with the run ID.
+            The newly generated token if one does not already exist
+            for the given run ID, otherwise None.
         """
 
     @abstractmethod

flwr/supercore/superexec/plugin/__init__.py

@@ -17,8 +17,10 @@
 
 from .clientapp_exec_plugin import ClientAppExecPlugin
 from .exec_plugin import ExecPlugin
+from .serverapp_exec_plugin import ServerAppExecPlugin
 
 __all__ = [
     "ClientAppExecPlugin",
     "ExecPlugin",
+    "ServerAppExecPlugin",
 ]

flwr/supercore/superexec/plugin/base_exec_plugin.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.
+# ==============================================================================
+"""Simple base Flower SuperExec plugin for app processes."""
+
+
+import os
+import subprocess
+from collections.abc import Sequence
+from typing import Optional
+
+from .exec_plugin import ExecPlugin
+
+
+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:
+            return None
+        return candidate_run_ids[0]
+
+    def launch_app(self, token: str, run_id: int) -> None:
+        """Launch the application associated with a given run ID and token."""
+        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]
+        # Launch the client app without waiting for it to complete.
+        # Since we don't need to manage the process, we intentionally avoid using
+        # a `with` statement. Suppress the pylint warning for it in this case.
+        # pylint: disable-next=consider-using-with
+        subprocess.Popen(cmds)

flwr/supercore/superexec/plugin/clientapp_exec_plugin.py

@@ -15,35 +15,14 @@
 """Simple Flower SuperExec plugin for ClientApp."""
 
 
-import os
-import subprocess
-from collections.abc import Sequence
-from typing import Optional
+from .base_exec_plugin import BaseExecPlugin
 
-from .exec_plugin import ExecPlugin
 
-
-class ClientAppExecPlugin(ExecPlugin):
+class ClientAppExecPlugin(BaseExecPlugin):
     """Simple Flower SuperExec plugin for ClientApp.
 
     The plugin always selects the first candidate run ID.
     """
 
-    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:
-            return None
-        return candidate_run_ids[0]
-
-    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 += ["--token", token]
-        cmds += ["--parent-pid", str(os.getpid())]
-        cmds += ["--flwr-dir", self.flwr_dir]
-        # Launch the client app without waiting for it to complete.
-        # Since we don't need to manage the process, we intentionally avoid using
-        # a `with` statement. Suppress the pylint warning for it in this case.
-        # pylint: disable-next=consider-using-with
-        subprocess.Popen(cmds)
+    command = "flwr-clientapp"
+    appio_api_address_arg = "--clientappio-api-address"

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/run_superexec.py

@@ -0,0 +1,113 @@
+# 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 typing import Optional
+
+from flwr.common.config import get_flwr_dir
+from flwr.common.exit_handlers import register_exit_handlers
+from flwr.common.grpc import create_channel, on_channel_state_change
+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 .plugin import ExecPlugin
+
+
+def run_superexec(
+    plugin_class: type[ExecPlugin],
+    stub_class: type[ClientAppIoStub],
+    appio_api_address: str,
+    flwr_dir: 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.
+    """
+    # 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_exit_handlers(
+        event_type=EventType.RUN_SUPEREXEC_LEAVE,
+        exit_message="SuperExec terminated gracefully.",
+        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()

flwr/supernode/nodestate/in_memory_nodestate.py

@@ -171,12 +171,12 @@ class InMemoryNodeState(NodeState):  # pylint: disable=too-many-instance-attribu
             ret -= set(self.token_store.keys())
             return list(ret)
 
-    def create_token(self, run_id: int) -> str:
+    def create_token(self, run_id: int) -> Optional[str]:
         """Create a token for the given run ID."""
         token = secrets.token_hex(FLWR_APP_TOKEN_LENGTH)  # Generate a random token
         with self.lock_token_store:
             if run_id in self.token_store:
-                raise ValueError("Token already created for this run ID")
+                return None  # Token already created for this run ID
             self.token_store[run_id] = token
             self.token_to_run_id[token] = run_id
         return token

flwr/supernode/runtime/run_clientapp.py

@@ -16,9 +16,6 @@
 
 
 import gc
-import os
-import threading
-import time
 from logging import DEBUG, ERROR, INFO
 from typing import Optional
 
@@ -55,8 +52,6 @@ from flwr.common.serde import (
 )
 from flwr.common.typing import Fab, Run
 from flwr.proto.appio_pb2 import (  # pylint: disable=E0611
-    ListAppsToLaunchRequest,
-    ListAppsToLaunchResponse,
     PullAppInputsRequest,
     PullAppInputsResponse,
     PullAppMessagesRequest,
@@ -64,11 +59,10 @@ from flwr.proto.appio_pb2 import (  # pylint: disable=E0611
     PushAppMessagesRequest,
     PushAppOutputsRequest,
     PushAppOutputsResponse,
-    RequestTokenRequest,
-    RequestTokenResponse,
 )
 from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
 from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
+from flwr.supercore.app_utils import simple_get_token, start_parent_process_monitor
 from flwr.supercore.utils import mask_string
 
 
@@ -101,7 +95,8 @@ def run_clientapp(  # pylint: disable=R0913, R0914, R0917
         while True:
             # If token is not set, loop until token is received from SuperNode
             if token is None:
-                token = get_token(stub)
+                log(DEBUG, "[flwr-clientapp] Request token")
+                token = simple_get_token(stub)
 
             # Pull Message, Context, Run and (optional) FAB from SuperNode
             message, context, run, fab = pull_clientappinputs(stub=stub, token=token)
@@ -173,36 +168,6 @@ def run_clientapp(  # pylint: disable=R0913, R0914, R0917
         channel.close()
 
 
-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 os.getppid() != parent_pid:
-                os.kill(os.getpid(), 9)
-
-    threading.Thread(target=monitor, daemon=True).start()
-
-
-def get_token(stub: ClientAppIoStub) -> str:
-    """Get a token from SuperNode."""
-    log(DEBUG, "[flwr-clientapp] Request token")
-    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
-
-
 def pull_clientappinputs(
     stub: ClientAppIoStub, token: str
 ) -> tuple[Message, Context, Run, Optional[Fab]]:

flwr/supernode/servicer/clientappio/clientappio_servicer.py

@@ -107,15 +107,10 @@ class ClientAppIoServicer(clientappio_pb2_grpc.ClientAppIoServicer):
         state = self.state_factory.state()
 
         # Attempt to create a token for the provided run ID
-        try:
-            token = state.create_token(request.run_id)
-        except ValueError:
-            # Return an empty token if A token already exists for this run ID,
-            # indicating the run is in progress
-            return RequestTokenResponse(token="")
+        token = state.create_token(request.run_id)
 
         # Return the token
-        return RequestTokenResponse(token=token)
+        return RequestTokenResponse(token=token or "")
 
     def GetRun(
         self, request: GetRunRequest, context: grpc.ServicerContext

{flwr_nightly-1.21.0.dev20250807.dist-info → flwr_nightly-1.21.0.dev20250809.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: flwr-nightly
-Version: 1.21.0.dev20250807
+Version: 1.21.0.dev20250809
 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.dev20250807.dist-info → flwr_nightly-1.21.0.dev20250809.dist-info}/RECORD

@@ -108,7 +108,7 @@ flwr/common/args.py,sha256=XFQ5PU0lU7NS1QCiKhhESHVeL8KSjcD3x8h4P3e5qlM,5298
 flwr/common/auth_plugin/__init__.py,sha256=DktrRcGZrRarLf7Jb_UlHtOyLp9_-kEplyq6PS5-vOA,988
 flwr/common/auth_plugin/auth_plugin.py,sha256=mM7SuphO4OsVAVJR1GErYVgYT83ZjxDzS_gha12bT9E,4855
 flwr/common/config.py,sha256=glcZDjco-amw1YfQcYTFJ4S1pt9APoexT-mf1QscuHs,13960
-flwr/common/constant.py,sha256=IMjx9E9iwQrbBuzsXtu0u-baFGENcWoyxU0caIvtSx0,8250
+flwr/common/constant.py,sha256=_E2ACR9F7oAaJcG0t1E7D9F7MtDyHVGnEe0_frCwMsQ,8710
 flwr/common/context.py,sha256=Be8obQR_OvEDy1OmshuUKxGRQ7Qx89mf5F4xlhkR10s,2407
 flwr/common/date.py,sha256=1ZT2cRSpC2DJqprOVTLXYCR_O2_OZR0zXO_brJ3LqWc,1554
 flwr/common/differential_privacy.py,sha256=FdlpdpPl_H_2HJa8CQM1iCUGBBQ5Dc8CzxmHERM-EoE,6148
@@ -151,7 +151,7 @@ flwr/common/secure_aggregation/secaggplus_constants.py,sha256=dGYhWOBMMDJcQH4_tQ
 flwr/common/secure_aggregation/secaggplus_utils.py,sha256=E_xU-Zd45daO1em7M6C2wOjFXVtJf-6tl7fp-7xq1wo,3214
 flwr/common/serde.py,sha256=dx66gumR1BpwK45qDwvDLd_05VoKfzkUzWZ7zuZi1-0,21960
 flwr/common/serde_utils.py,sha256=krx2C_W31KpfmDqnDCtULoTkT8WKweWTJ7FHYWtF1r4,5815
-flwr/common/telemetry.py,sha256=jF47v0SbnBd43XamHtl3wKxs3knFUY2p77cm_2lzZ8M,8762
+flwr/common/telemetry.py,sha256=xfx3KLFQKy0Qx8P7MAsOQxr5J3sEAQF5Kr5J-4jPz-o,8859
 flwr/common/typing.py,sha256=B8z50fv8K0H4F5m8XRPBoWy-qqbNMyQXBAaaSuzfbnY,6936
 flwr/common/version.py,sha256=7GAGzPn73Mkh09qhrjbmjZQtcqVhBuzhFBaK4Mk4VRk,1325
 flwr/compat/__init__.py,sha256=gbfDQKKKMZzi3GswyVRgyLdDlHiWj3wU6dg7y6m5O_s,752
@@ -250,7 +250,7 @@ flwr/server/server.py,sha256=39m4FSN2T-uVA-no9nstN0eWW0co-IUUAIMmpd3V7Jc,17893
 flwr/server/server_app.py,sha256=8uagoZX-3CY3tazPqkIV9jY-cN0YrRRrDmVe23o0AV0,9515
 flwr/server/server_config.py,sha256=e_6ddh0riwOJsdNn2BFev344uMWfDk9n7dyjNpPgm1w,1349
 flwr/server/serverapp/__init__.py,sha256=xcC0T_MQSMS9cicUzUUpMNCOsF2d8Oh_8jvnoBLuZvo,800
-flwr/server/serverapp/app.py,sha256=k0wAdZiMAEz7WsUigxv038I5Eel3vXwuSqGGj2HtX3c,9524
+flwr/server/serverapp/app.py,sha256=-IZY02Ym6AREMPaLld6WCD9mjDz7wsqfYgLLJxpy2pg,10433
 flwr/server/serverapp_components.py,sha256=dfSqmrsVy3arKXpl3ZIBQWdV8rehfIms8aJooyzdmEM,2118
 flwr/server/strategy/__init__.py,sha256=HhsSWMWaC7oCb2g7Kqn1MBKdrfvgi8VxACy9ZL706Q0,2836
 flwr/server/strategy/aggregate.py,sha256=smlKKy-uFUuuFR12vlclucnwSQWRz78R79-Km4RWqbw,13978
@@ -298,14 +298,14 @@ flwr/server/superlink/fleet/vce/backend/backend.py,sha256=-wDHjgAy5mrfEgXj0GxkJI
 flwr/server/superlink/fleet/vce/backend/raybackend.py,sha256=Hx9hxL7lju1_VJoAwkhBOGerZ3628u0P1zgkPhGWRPY,7154
 flwr/server/superlink/fleet/vce/vce_api.py,sha256=xSjQbBYHmUTinw7Q_-UxqR7qt07kqj9FCSpPYRsUKf8,12909
 flwr/server/superlink/linkstate/__init__.py,sha256=OtsgvDTnZLU3k0sUbkHbqoVwW6ql2FDmb6uT6DbNkZo,1064
-flwr/server/superlink/linkstate/in_memory_linkstate.py,sha256=jm5ZB6kePnikMEIN841bHedoC8Cjnve5JI2v6Wy8v6E,27886
+flwr/server/superlink/linkstate/in_memory_linkstate.py,sha256=eNjjQp6dJ_Qz54fYeOZ9XFebbB_k9syhBB6N2rXRTsA,27891
 flwr/server/superlink/linkstate/linkstate.py,sha256=TCLM9wZa2XGHs55B3LP9j5-WtUPhBjOUdMKQJELG2oY,13287
 flwr/server/superlink/linkstate/linkstate_factory.py,sha256=8RlosqSpKOoD_vhUUQPY0jtE3A84GeF96Z7sWNkRRcA,2069
-flwr/server/superlink/linkstate/sqlite_linkstate.py,sha256=ROAdb_uvaCsJa-AJbczbPFOpdaFiof2Y1s1fSBO6YUo,45508
+flwr/server/superlink/linkstate/sqlite_linkstate.py,sha256=NIJ1BDcj54TUpNaeb23af38wQE-TM6rnYVMJncJVKQ0,45503
 flwr/server/superlink/linkstate/utils.py,sha256=IeLh7iGRCHU5MEWOl7iriaSE4L__8GWOa2OleXadK5M,15444
 flwr/server/superlink/serverappio/__init__.py,sha256=Fy4zJuoccZe5mZSEIpOmQvU6YeXFBa1M4eZuXXmJcn8,717
 flwr/server/superlink/serverappio/serverappio_grpc.py,sha256=zcvzDhCAnlFxAwCiJUHNm6IE7-rk5jeZqSmPgjEY3AU,2307
-flwr/server/superlink/serverappio/serverappio_servicer.py,sha256=DmYfjHQLya7LD4rLBLhDCdH9XTBgV8X790D3tdwHZpk,19096
+flwr/server/superlink/serverappio/serverappio_servicer.py,sha256=3C_0boRbYuY1Vlf0DRGzBvTUX-D5UUzxYkFihSMZf-A,20094
 flwr/server/superlink/simulation/__init__.py,sha256=Ry8DrNaZCMcQXvUc4FoCN2m3dvUQgWjasfp015o3Ec4,718
 flwr/server/superlink/simulation/simulationio_grpc.py,sha256=VqWKxjpd4bCgPFKsgtIZPk9YcG0kc1EEmr5k20EKty4,2205
 flwr/server/superlink/simulation/simulationio_servicer.py,sha256=m1T1zvEn81jlfx9hVTqmeWxAu6APCS2YW8l5O0OQvhU,7724
@@ -331,8 +331,11 @@ flwr/simulation/ray_transport/utils.py,sha256=KrexpWYCF-dAF3UHc9yDbPQWO-ahMT-BbD
 flwr/simulation/run_simulation.py,sha256=-sp3dNZcp7MCAH0BlmZpVcFAGvozRdYXRdDYcH_2Zxk,20838
 flwr/simulation/simulationio_connection.py,sha256=mzS1C6EEREwQDPceDo30anAasmTDLb9qqV2tXlBhOUA,3494
 flwr/supercore/__init__.py,sha256=pqkFoow_E6UhbBlhmoD1gmTH-33yJRhBsIZqxRPFZ7U,755
+flwr/supercore/app_utils.py,sha256=L4S6yNE7mAm0WFww8y2VruOouGfQOz_sguA9o9DqGuI,2029
+flwr/supercore/cli/__init__.py,sha256=EDl2aO-fuQfxSbL-T1W9RAfA2N0hpWHmqX_GSwblJbQ,845
+flwr/supercore/cli/flower_superexec.py,sha256=i1quvC41nXUAscIhpLZ6gi834KFM_cUDq5rdbDjacbs,3235
 flwr/supercore/corestate/__init__.py,sha256=Vau6-L_JG5QzNqtCTa9xCKGGljc09wY8avZmIjSJemg,774
-flwr/supercore/corestate/corestate.py,sha256=vfZxZ6ddpg5ej3BJCJdaumQImElXG-lIaj-942xdT90,2255
+flwr/supercore/corestate/corestate.py,sha256=rDAWWeG5DcpCyQso9Z3RhwL4zr2IroPlRMcDzqoSu8s,2328
 flwr/supercore/ffs/__init__.py,sha256=U3KXwG_SplEvchat27K0LYPoPHzh-cwwT_NHsGlYMt8,908
 flwr/supercore/ffs/disk_ffs.py,sha256=c5VywSaRnq3XM_zuJptNtsF2HFwsRK0pvBd5-5CNONs,3272
 flwr/supercore/ffs/ffs.py,sha256=6w7wy71i7tbuJwqEgdeCa49JejXMEof3jujURN_R7Rg,2395
@@ -347,9 +350,12 @@ flwr/supercore/object_store/object_store.py,sha256=J-rI3X7ET-F6dqOyM-UfHKCCQtPJ_
 flwr/supercore/object_store/object_store_factory.py,sha256=QVwE2ywi7vsj2iKfvWWnNw3N_I7Rz91NUt2RpcbJ7iM,1527
 flwr/supercore/object_store/utils.py,sha256=DcPbrb9PenloAPoQRiKiXX9DrDfpXcSyY0cZpgn4PeQ,1680
 flwr/supercore/superexec/__init__.py,sha256=XKX208hZ6a9gZ4KT9kMqfpCtp_8VGxekzKFfHSu2esQ,707
-flwr/supercore/superexec/plugin/__init__.py,sha256=OH5WYxZssOUzOVya3na4yHH0bRwtYmnottUreJT9R20,868
-flwr/supercore/superexec/plugin/clientapp_exec_plugin.py,sha256=qX7vcB2n4crlfTTHKNqV0jHBmk8DiCIRuGDwLGAhP7g,1975
+flwr/supercore/superexec/plugin/__init__.py,sha256=pdnH-bcyqjGyWqEhYTfnZFaLhw5v43HpUB--koNttSU,950
+flwr/supercore/superexec/plugin/base_exec_plugin.py,sha256=fL-Ufc9Dp56OhWOzNSJUc7HumbkuSDYqZKwde2opG4g,2074
+flwr/supercore/superexec/plugin/clientapp_exec_plugin.py,sha256=9FT6ufEqV5K9g4FaAB9lVDbIv-VCH5LcxT4YKy23roE,1035
 flwr/supercore/superexec/plugin/exec_plugin.py,sha256=w3jmtxdv7ov_EdAgifKcm4q8nV39e2Xna4sNjqClwOM,2447
+flwr/supercore/superexec/plugin/serverapp_exec_plugin.py,sha256=IwRzdPV-cSKwrP2krGh0De4IkAuxsmgK0WU6J-2GXqM,1035
+flwr/supercore/superexec/run_superexec.py,sha256=MNmQd6HfPr7Ec5RvTsH6-pDnwGL8bbiqbZ5mkHaQQPY,3873
 flwr/supercore/utils.py,sha256=ebuHMbeA8eXisX0oMPqBK3hk7uVnIE_yiqWVz8YbkpQ,1324
 flwr/superexec/__init__.py,sha256=YFqER0IJc1XEWfsX6AxZ9LSRq0sawPYrNYki-brvTIc,715
 flwr/superexec/deployment.py,sha256=CEgWfkN_lH6Vci03RjwKLENw2z6kxNvUdVEErPbqYDY,830
@@ -372,16 +378,16 @@ flwr/supernode/cli/__init__.py,sha256=JuEMr0-s9zv-PEWKuLB9tj1ocNfroSyNJ-oyv7ati9
 flwr/supernode/cli/flower_supernode.py,sha256=fAkk9zGhoP8Sv05EkdXRiCtirTAzWkSZBqRoaDdgflk,8529
 flwr/supernode/cli/flwr_clientapp.py,sha256=zaro6BoUEmfKIPQYuyJ9oR4rrHSS3bufhEqxcTo5VZU,3153
 flwr/supernode/nodestate/__init__.py,sha256=CyLLObbmmVgfRO88UCM0VMait1dL57mUauUDfuSHsbU,976
-flwr/supernode/nodestate/in_memory_nodestate.py,sha256=LF3AbaW0bcZHY5yKWwUJSU2RZbMynt-YjFysGqvTOQY,7338
+flwr/supernode/nodestate/in_memory_nodestate.py,sha256=rr_tg7YXhf_seYFipSB59TAfheKPratx3rrvHUOJ80g,7343
 flwr/supernode/nodestate/nodestate.py,sha256=jCOewZyctecMxsM0-_-pQwef9P3O5QjnKCgCGyx2PK4,5047
 flwr/supernode/nodestate/nodestate_factory.py,sha256=UYTDCcwK_baHUmkzkJDxL0UEqvtTfOMlQRrROMCd0Xo,1430
 flwr/supernode/runtime/__init__.py,sha256=JQdqd2EMTn-ORMeTvewYYh52ls0YKP68jrps1qioxu4,718
-flwr/supernode/runtime/run_clientapp.py,sha256=efocWcTe2ufkhe4BzMGgxe0COq9aDyJ6HzXwQ8ZaIAU,10551
+flwr/supernode/runtime/run_clientapp.py,sha256=vAeBTgIi4SmV4IRq1dSjXaxrFUPEeHg-nkvt5iAZ1Zc,9675
 flwr/supernode/servicer/__init__.py,sha256=lucTzre5WPK7G1YLCfaqg3rbFWdNSb7ZTt-ca8gxdEo,717
 flwr/supernode/servicer/clientappio/__init__.py,sha256=7Oy62Y_oijqF7Dxi6tpcUQyOpLc_QpIRZ83NvwmB0Yg,813
-flwr/supernode/servicer/clientappio/clientappio_servicer.py,sha256=Egp8V_Z3k9wWJUhXEXVWyf-g9iZ_lI6VcoKQTtG9uQg,10454
+flwr/supernode/servicer/clientappio/clientappio_servicer.py,sha256=nIHRu38EWK-rpNOkcgBRAAKwYQQWFeCwu0lkO7OPZGQ,10239
 flwr/supernode/start_client_internal.py,sha256=iqJR8WbCW-8RQIRNwARZYoxhnlaAo5KnluCOEfRoLWM,21020
-flwr_nightly-1.21.0.dev20250807.dist-info/METADATA,sha256=_2ScWM9obUF2NYThP8IqpB2AHIL84ChKeSWcS6ikVF4,15966
-flwr_nightly-1.21.0.dev20250807.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-flwr_nightly-1.21.0.dev20250807.dist-info/entry_points.txt,sha256=jNpDXGBGgs21RqUxelF_jwGaxtqFwm-MQyfz-ZqSjrA,367
-flwr_nightly-1.21.0.dev20250807.dist-info/RECORD,,
+flwr_nightly-1.21.0.dev20250809.dist-info/METADATA,sha256=k1dHkYUIlLAE-9AG-gUw8_-KrH8DLnz5mPsIcCfDIpc,15966
+flwr_nightly-1.21.0.dev20250809.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+flwr_nightly-1.21.0.dev20250809.dist-info/entry_points.txt,sha256=hxHD2ixb_vJFDOlZV-zB4Ao32_BQlL34ftsDh1GXv14,420
+flwr_nightly-1.21.0.dev20250809.dist-info/RECORD,,

{flwr_nightly-1.21.0.dev20250807.dist-info → flwr_nightly-1.21.0.dev20250809.dist-info}/entry_points.txt

@@ -1,5 +1,6 @@
 [console_scripts]
 flower-simulation=flwr.simulation.run_simulation:run_simulation_from_cli
+flower-superexec=flwr.supercore.cli:flower_superexec
 flower-superlink=flwr.server.app:run_superlink
 flower-supernode=flwr.supernode.cli:flower_supernode
 flwr=flwr.cli.app:app