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

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,21 @@ 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 .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 +46,41 @@ 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,
 ) -> 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,
     )
     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 +88,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)
 

flwr/{superexec/exec_servicer.py → superlink/servicer/control/control_servicer.py}

@@ -12,9 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""SuperExec API servicer."""
+"""Control API servicer."""
 
 
+import hashlib
 import time
 from collections.abc import Generator
 from logging import ERROR, INFO
@@ -22,11 +23,13 @@ from typing import Any, Optional, cast
 
 import grpc
 
-from flwr.common import now
-from flwr.common.auth_plugin import ExecAuthPlugin
+from flwr.cli.config_utils import get_fab_metadata
+from flwr.common import Context, RecordDict, now
+from flwr.common.auth_plugin import ControlAuthPlugin
 from flwr.common.constant import (
     FAB_MAX_SIZE,
     LOG_STREAM_INTERVAL,
+    NO_USER_AUTH_MESSAGE,
     RUN_ID_NOT_FOUND_MESSAGE,
     Status,
     SubStatus,
@@ -37,9 +40,9 @@ from flwr.common.serde import (
     run_to_proto,
     user_config_from_proto,
 )
-from flwr.common.typing import Run, RunStatus
-from flwr.proto import exec_pb2_grpc  # pylint: disable=E0611
-from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+from flwr.common.typing import Fab, Run, RunStatus
+from flwr.proto import control_pb2_grpc  # pylint: disable=E0611
+from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     GetAuthTokensRequest,
     GetAuthTokensResponse,
     GetLoginDetailsRequest,
@@ -57,33 +60,33 @@ from flwr.server.superlink.linkstate import LinkState, LinkStateFactory
 from flwr.supercore.ffs import FfsFactory
 from flwr.supercore.object_store import ObjectStore, ObjectStoreFactory
 
-from .exec_user_auth_interceptor import shared_account_info
-from .executor import Executor
+from .control_user_auth_interceptor import shared_account_info
 
 
-class ExecServicer(exec_pb2_grpc.ExecServicer):
-    """SuperExec API servicer."""
+class ControlServicer(control_pb2_grpc.ControlServicer):
+    """Control API servicer."""
 
     def __init__(  # pylint: disable=R0913, R0917
         self,
         linkstate_factory: LinkStateFactory,
         ffs_factory: FfsFactory,
         objectstore_factory: ObjectStoreFactory,
-        executor: Executor,
-        auth_plugin: Optional[ExecAuthPlugin] = None,
+        is_simulation: bool,
+        auth_plugin: Optional[ControlAuthPlugin] = None,
     ) -> None:
         self.linkstate_factory = linkstate_factory
         self.ffs_factory = ffs_factory
         self.objectstore_factory = objectstore_factory
-        self.executor = executor
-        self.executor.initialize(linkstate_factory, ffs_factory)
+        self.is_simulation = is_simulation
         self.auth_plugin = auth_plugin
 
     def StartRun(
         self, request: StartRunRequest, context: grpc.ServicerContext
     ) -> StartRunResponse:
         """Create run ID."""
-        log(INFO, "ExecServicer.StartRun")
+        log(INFO, "ControlServicer.StartRun")
+        state = self.linkstate_factory.state()
+        ffs = self.ffs_factory.ffs()
 
         if len(request.fab.content) > FAB_MAX_SIZE:
             log(
@@ -94,24 +97,60 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
             return StartRunResponse()
 
         flwr_aid = shared_account_info.get().flwr_aid if self.auth_plugin else None
-        run_id = self.executor.start_run(
-            request.fab.content,
-            user_config_from_proto(request.override_config),
-            config_record_from_proto(request.federation_options),
-            flwr_aid,
-        )
+        override_config = user_config_from_proto(request.override_config)
+        federation_options = config_record_from_proto(request.federation_options)
+        fab_file = request.fab.content
+
+        try:
+            # Check that num-supernodes is set
+            if self.is_simulation and "num-supernodes" not in federation_options:
+                raise ValueError(
+                    "Federation options doesn't contain key `num-supernodes`."
+                )
+
+            # Create run
+            fab = Fab(hashlib.sha256(fab_file).hexdigest(), fab_file)
+            fab_hash = ffs.put(fab.content, {})
+            if fab_hash != fab.hash_str:
+                raise RuntimeError(
+                    f"FAB ({fab.hash_str}) hash from request doesn't match contents"
+                )
+            fab_id, fab_version = get_fab_metadata(fab.content)
+
+            run_id = state.create_run(
+                fab_id,
+                fab_version,
+                fab_hash,
+                override_config,
+                federation_options,
+                flwr_aid,
+            )
+
+            # Create an empty context for the Run
+            context = Context(
+                run_id=run_id,
+                node_id=0,
+                node_config={},
+                state=RecordDict(),
+                run_config={},
+            )
+
+            # Register the context at the LinkState
+            state.set_serverapp_context(run_id=run_id, context=context)
 
-        if run_id is None:
-            log(ERROR, "Executor failed to start run")
+        # pylint: disable-next=broad-except
+        except Exception as e:
+            log(ERROR, "Could not start run: %s", str(e))
             return StartRunResponse()
 
+        log(INFO, "Created run %s", str(run_id))
         return StartRunResponse(run_id=run_id)
 
     def StreamLogs(  # pylint: disable=C0103
         self, request: StreamLogsRequest, context: grpc.ServicerContext
     ) -> Generator[StreamLogsResponse, Any, None]:
         """Get logs."""
-        log(INFO, "ExecServicer.StreamLogs")
+        log(INFO, "ControlServicer.StreamLogs")
         state = self.linkstate_factory.state()
 
         # Retrieve run ID and run
@@ -158,7 +197,7 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         self, request: ListRunsRequest, context: grpc.ServicerContext
     ) -> ListRunsResponse:
         """Handle `flwr ls` command."""
-        log(INFO, "ExecServicer.List")
+        log(INFO, "ControlServicer.List")
         state = self.linkstate_factory.state()
 
         # Build a set of run IDs for `flwr ls --runs`
@@ -204,7 +243,7 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         self, request: StopRunRequest, context: grpc.ServicerContext
     ) -> StopRunResponse:
         """Stop a given run ID."""
-        log(INFO, "ExecServicer.StopRun")
+        log(INFO, "ControlServicer.StopRun")
         state = self.linkstate_factory.state()
 
         # Retrieve run ID and run
@@ -249,11 +288,11 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         self, request: GetLoginDetailsRequest, context: grpc.ServicerContext
     ) -> GetLoginDetailsResponse:
         """Start login."""
-        log(INFO, "ExecServicer.GetLoginDetails")
+        log(INFO, "ControlServicer.GetLoginDetails")
         if self.auth_plugin is None:
             context.abort(
                 grpc.StatusCode.UNIMPLEMENTED,
-                "ExecServicer initialized without user authentication",
+                NO_USER_AUTH_MESSAGE,
             )
             raise grpc.RpcError()  # This line is unreachable
 
@@ -276,11 +315,11 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         self, request: GetAuthTokensRequest, context: grpc.ServicerContext
     ) -> GetAuthTokensResponse:
         """Get auth token."""
-        log(INFO, "ExecServicer.GetAuthTokens")
+        log(INFO, "ControlServicer.GetAuthTokens")
         if self.auth_plugin is None:
             context.abort(
                 grpc.StatusCode.UNIMPLEMENTED,
-                "ExecServicer initialized without user authentication",
+                NO_USER_AUTH_MESSAGE,
             )
             raise grpc.RpcError()  # This line is unreachable
 

flwr/{superexec/exec_user_auth_interceptor.py → superlink/servicer/control/control_user_auth_interceptor.py}

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower Exec API interceptor."""
+"""Flower Control API interceptor."""
 
 
 import contextvars
@@ -20,9 +20,9 @@ from typing import Any, Callable, Union
 
 import grpc
 
-from flwr.common.auth_plugin import ExecAuthPlugin, ExecAuthzPlugin
+from flwr.common.auth_plugin import ControlAuthPlugin, ControlAuthzPlugin
 from flwr.common.typing import AccountInfo
-from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+from flwr.proto.control_pb2 import (  # pylint: disable=E0611
     GetAuthTokensRequest,
     GetAuthTokensResponse,
     GetLoginDetailsRequest,
@@ -50,13 +50,13 @@ shared_account_info: contextvars.ContextVar[AccountInfo] = contextvars.ContextVa
 )
 
 
-class ExecUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
-    """Exec API interceptor for user authentication."""
+class ControlUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
+    """Control API interceptor for user authentication."""
 
     def __init__(
         self,
-        auth_plugin: ExecAuthPlugin,
-        authz_plugin: ExecAuthzPlugin,
+        auth_plugin: ControlAuthPlugin,
+        authz_plugin: ControlAuthzPlugin,
     ):
         self.auth_plugin = auth_plugin
         self.authz_plugin = authz_plugin
@@ -72,12 +72,12 @@ class ExecUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
         by validating auth metadata sent by the user. Continue RPC call if user is
         authenticated, 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_auth_unary_method_handler(method_handler)
 

flwr/supernode/cli/flower_supernode.py

@@ -41,6 +41,7 @@ from flwr.common.constant import (
 )
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.logger import log
+from flwr.supercore.grpc_health import add_args_health
 from flwr.supernode.start_client_internal import start_client_internal
 
 
@@ -79,6 +80,7 @@ def flower_supernode() -> None:
         flwr_path=args.flwr_dir,
         isolation=args.isolation,
         clientappio_api_address=args.clientappio_api_address,
+        health_server_address=args.health_server_address,
     )
 
 
@@ -118,6 +120,7 @@ def _parse_args_run_supernode() -> argparse.ArgumentParser:
         help="ClientAppIo API (gRPC) server address (IPv4, IPv6, or a domain name). "
         f"By default, it is set to {CLIENTAPPIO_API_DEFAULT_SERVER_ADDRESS}.",
     )
+    add_args_health(parser)
 
     return parser
 

flwr/supernode/cli/flwr_clientapp.py

@@ -19,9 +19,12 @@ import argparse
 from logging import DEBUG, INFO
 
 from flwr.common.args import add_args_flwr_app_common
-from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS
+from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS, ExecPluginType
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.logger import log
+from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
+from flwr.supercore.superexec.plugin import ClientAppExecPlugin
+from flwr.supercore.superexec.run_superexec import run_with_deprecation_warning
 from flwr.supercore.utils import mask_string
 from flwr.supernode.runtime.run_clientapp import run_clientapp
 
@@ -35,6 +38,20 @@ def flwr_clientapp() -> None:
             "flwr-clientapp does not support TLS yet.",
         )
 
+    # Disallow long-running `flwr-clientapp` processes
+    if args.token is None:
+        run_with_deprecation_warning(
+            cmd="flwr-clientapp",
+            plugin_type=ExecPluginType.CLIENT_APP,
+            plugin_class=ClientAppExecPlugin,
+            stub_class=ClientAppIoStub,
+            appio_api_address=args.clientappio_api_address,
+            flwr_dir=args.flwr_dir,
+            parent_pid=args.parent_pid,
+            warn_run_once=args.run_once,
+        )
+        return
+
     log(INFO, "Start `flwr-clientapp` process")
     log(
         DEBUG,
@@ -45,7 +62,6 @@ def flwr_clientapp() -> None:
     )
     run_clientapp(
         clientappio_api_address=args.clientappio_api_address,
-        run_once=(args.token is not None) or args.run_once,
         token=args.token,
         flwr_dir=args.flwr_dir,
         certificates=None,
@@ -65,24 +81,5 @@ def _parse_args_run_flwr_clientapp() -> argparse.ArgumentParser:
         help="Address of SuperNode's ClientAppIo API (IPv4, IPv6, or a domain name)."
         f"By default, it is set to {CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS}.",
     )
-    parser.add_argument(
-        "--token",
-        type=str,
-        required=False,
-        help="Unique token generated by SuperNode for each ClientApp 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",
-        help="When set, this process will start a single ClientApp for a pending "
-        "message. If there is no pending message, the process will exit.",
-    )
     add_args_flwr_app_common(parser=parser)
     return parser

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

@@ -15,15 +15,16 @@
 """Abstract base class NodeState."""
 
 
-from abc import ABC, abstractmethod
+from abc import abstractmethod
 from collections.abc import Sequence
 from typing import Optional
 
 from flwr.common import Context, Message
 from flwr.common.typing import Run
+from flwr.supercore.corestate import CoreState
 
 
-class NodeState(ABC):
+class NodeState(CoreState):
     """Abstract base class for node state."""
 
     @abstractmethod
@@ -168,60 +169,3 @@ class NodeState(ABC):
         Sequence[int]
             Sequence of run IDs with pending messages.
         """
-
-    @abstractmethod
-    def create_token(self, run_id: int) -> 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
-            A unique token associated with the run ID.
-        """
-
-    @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.
-        """