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

flwr/supercore/superexec/run_superexec.py

@@ -0,0 +1,199 @@
+# 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 Any, Optional, Union
+
+from flwr.common.config import get_flwr_dir
+from flwr.common.exit import ExitCode, flwr_exit, 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,
+    plugin_config: Optional[dict[str, Any]] = None,
+    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.
+    plugin_config : Optional[dict[str, Any]] (default: None)
+        The configuration dictionary for the plugin. If `None`, the plugin will use
+        its default configuration.
+    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,
+    )
+
+    # Load plugin configuration from file if provided
+    try:
+        if plugin_config is not None:
+            plugin.load_config(plugin_config)
+    except (KeyError, ValueError) as e:
+        flwr_exit(
+            code=ExitCode.SUPEREXEC_INVALID_PLUGIN_CONFIG,
+            message=f"Invalid plugin config: {e!r}",
+        )
+
+    # 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/artifact_provider/__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.
+# ==============================================================================
+"""ArtifactProvider for SuperLink."""
+
+
+from .artifact_provider import ArtifactProvider
+
+__all__ = [
+    "ArtifactProvider",
+]

flwr/superlink/artifact_provider/artifact_provider.py

@@ -0,0 +1,37 @@
+# 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 for ArtifactProvider."""
+
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class ArtifactProvider(ABC):
+    """ArtifactProvider interface for providing artifact download links."""
+
+    @abstractmethod
+    def get_url(self, run_id: int) -> Optional[str]:
+        """Return the artifact download link for the given run ID."""
+
+    @property
+    @abstractmethod
+    def output_dir(self) -> str:
+        """Permanent storage directory."""
+
+    @property
+    @abstractmethod
+    def tmp_dir(self) -> str:
+        """Temporary storage directory."""

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)

flwr/{superexec/exec_grpc.py → superlink/servicer/control/control_grpc.py}

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""SuperExec gRPC API."""
+"""Control API server."""
 
 
 from logging import INFO
@@ -21,23 +21,22 @@ from typing import Optional
 import grpc
 
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
-from flwr.common.auth_plugin import ExecAuthPlugin, ExecAuthzPlugin
+from flwr.common.auth_plugin import ControlAuthPlugin, ControlAuthzPlugin
 from flwr.common.event_log_plugin import EventLogWriterPlugin
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.grpc import generic_create_grpc_server
 from flwr.common.logger import log
-from flwr.common.typing import UserConfig
-from flwr.proto.exec_pb2_grpc import add_ExecServicer_to_server
+from flwr.proto.control_pb2_grpc import add_ControlServicer_to_server
 from flwr.server.superlink.linkstate import LinkStateFactory
 from flwr.supercore.ffs import FfsFactory
 from flwr.supercore.license_plugin import LicensePlugin
 from flwr.supercore.object_store import ObjectStoreFactory
-from flwr.superexec.exec_event_log_interceptor import ExecEventLogInterceptor
-from flwr.superexec.exec_license_interceptor import ExecLicenseInterceptor
-from flwr.superexec.exec_user_auth_interceptor import ExecUserAuthInterceptor
+from flwr.superlink.artifact_provider import ArtifactProvider
 
-from .exec_servicer import ExecServicer
-from .executor import Executor
+from .control_event_log_interceptor import ControlEventLogInterceptor
+from .control_license_interceptor import ControlLicenseInterceptor
+from .control_servicer import ControlServicer
+from .control_user_auth_interceptor import ControlUserAuthInterceptor
 
 try:
     from flwr.ee import get_license_plugin
@@ -48,44 +47,43 @@ except ImportError:
 
 
 # pylint: disable-next=too-many-arguments,too-many-positional-arguments,too-many-locals
-def run_exec_api_grpc(
+def run_control_api_grpc(
     address: str,
-    executor: Executor,
     state_factory: LinkStateFactory,
     ffs_factory: FfsFactory,
     objectstore_factory: ObjectStoreFactory,
     certificates: Optional[tuple[bytes, bytes, bytes]],
-    config: UserConfig,
-    auth_plugin: Optional[ExecAuthPlugin] = None,
-    authz_plugin: Optional[ExecAuthzPlugin] = None,
+    is_simulation: bool,
+    auth_plugin: Optional[ControlAuthPlugin] = None,
+    authz_plugin: Optional[ControlAuthzPlugin] = None,
     event_log_plugin: Optional[EventLogWriterPlugin] = None,
+    artifact_provider: Optional[ArtifactProvider] = None,
 ) -> grpc.Server:
-    """Run Exec API (gRPC, request-response)."""
-    executor.set_config(config)
-
+    """Run Control API (gRPC, request-response)."""
     license_plugin: Optional[LicensePlugin] = get_license_plugin()
     if license_plugin and not license_plugin.check_license():
         flwr_exit(ExitCode.SUPERLINK_LICENSE_INVALID)
 
-    exec_servicer: grpc.Server = ExecServicer(
+    control_servicer: grpc.Server = ControlServicer(
         linkstate_factory=state_factory,
         ffs_factory=ffs_factory,
         objectstore_factory=objectstore_factory,
-        executor=executor,
+        is_simulation=is_simulation,
         auth_plugin=auth_plugin,
+        artifact_provider=artifact_provider,
     )
     interceptors: list[grpc.ServerInterceptor] = []
     if license_plugin is not None:
-        interceptors.append(ExecLicenseInterceptor(license_plugin))
+        interceptors.append(ControlLicenseInterceptor(license_plugin))
     if auth_plugin is not None and authz_plugin is not None:
-        interceptors.append(ExecUserAuthInterceptor(auth_plugin, authz_plugin))
+        interceptors.append(ControlUserAuthInterceptor(auth_plugin, authz_plugin))
     # Event log interceptor must be added after user auth interceptor
     if event_log_plugin is not None:
-        interceptors.append(ExecEventLogInterceptor(event_log_plugin))
+        interceptors.append(ControlEventLogInterceptor(event_log_plugin))
         log(INFO, "Flower event logging enabled")
-    exec_add_servicer_to_server_fn = add_ExecServicer_to_server
-    exec_grpc_server = generic_create_grpc_server(
-        servicer_and_add_fn=(exec_servicer, exec_add_servicer_to_server_fn),
+    control_add_servicer_to_server_fn = add_ControlServicer_to_server
+    control_grpc_server = generic_create_grpc_server(
+        servicer_and_add_fn=(control_servicer, control_add_servicer_to_server_fn),
         server_address=address,
         max_message_length=GRPC_MAX_MESSAGE_LENGTH,
         certificates=certificates,
@@ -93,14 +91,14 @@ def run_exec_api_grpc(
     )
 
     if auth_plugin is None:
-        log(INFO, "Flower Deployment Engine: Starting Exec API on %s", address)
+        log(INFO, "Flower Deployment Runtime: Starting Control API on %s", address)
     else:
         log(
             INFO,
-            "Flower Deployment Engine: Starting Exec API with user "
+            "Flower Deployment Runtime: Starting Control API with user "
             "authentication on %s",
             address,
         )
-    exec_grpc_server.start()
+    control_grpc_server.start()
 
-    return exec_grpc_server
+    return control_grpc_server

flwr/{superexec/exec_license_interceptor.py → superlink/servicer/control/control_license_interceptor.py}

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower Exec API license interceptor."""
+"""Flower Control API license interceptor."""
 
 
 from collections.abc import Iterator
@@ -24,8 +24,8 @@ from google.protobuf.message import Message as GrpcMessage
 from flwr.supercore.license_plugin import LicensePlugin
 
 
-class ExecLicenseInterceptor(grpc.ServerInterceptor):  # type: ignore
-    """Exec API interceptor for license checking."""
+class ControlLicenseInterceptor(grpc.ServerInterceptor):  # type: ignore
+    """Control API interceptor for license checking."""
 
     def __init__(self, license_plugin: LicensePlugin) -> None:
         """Initialize the interceptor with a license plugin."""
@@ -42,12 +42,12 @@ class ExecLicenseInterceptor(grpc.ServerInterceptor):  # type: ignore
         Continue RPC call if license check is enabled and passes, 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)
         return self._generic_license_unary_method_handler(method_handler)