flwr 1.18.0__py3-none-any.whl → 1.19.0__py3-none-any.whl

flwr/superexec/exec_servicer.py

@@ -18,21 +18,25 @@
 import time
 from collections.abc import Generator
 from logging import ERROR, INFO
-from typing import Any, Optional
-from uuid import UUID
+from typing import Any, Optional, cast
 
 import grpc
 
 from flwr.common import now
 from flwr.common.auth_plugin import ExecAuthPlugin
-from flwr.common.constant import LOG_STREAM_INTERVAL, Status, SubStatus
+from flwr.common.constant import (
+    LOG_STREAM_INTERVAL,
+    RUN_ID_NOT_FOUND_MESSAGE,
+    Status,
+    SubStatus,
+)
 from flwr.common.logger import log
 from flwr.common.serde import (
     config_record_from_proto,
     run_to_proto,
     user_config_from_proto,
 )
-from flwr.common.typing import RunStatus
+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
     GetAuthTokensRequest,
@@ -50,22 +54,26 @@ from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
 )
 from flwr.server.superlink.ffs.ffs_factory import FfsFactory
 from flwr.server.superlink.linkstate import LinkState, LinkStateFactory
+from flwr.supercore.object_store import ObjectStore, ObjectStoreFactory
 
+from .exec_user_auth_interceptor import shared_account_info
 from .executor import Executor
 
 
 class ExecServicer(exec_pb2_grpc.ExecServicer):
     """SuperExec API servicer."""
 
-    def __init__(
+    def __init__(  # pylint: disable=R0913, R0917
         self,
         linkstate_factory: LinkStateFactory,
         ffs_factory: FfsFactory,
+        objectstore_factory: ObjectStoreFactory,
         executor: Executor,
         auth_plugin: Optional[ExecAuthPlugin] = 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.auth_plugin = auth_plugin
@@ -76,10 +84,12 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         """Create run ID."""
         log(INFO, "ExecServicer.StartRun")
 
+        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,
         )
 
         if run_id is None:
@@ -95,12 +105,20 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         log(INFO, "ExecServicer.StreamLogs")
         state = self.linkstate_factory.state()
 
-        # Retrieve run ID
+        # Retrieve run ID and run
         run_id = request.run_id
+        run = state.get_run(run_id)
 
         # Exit if `run_id` not found
-        if not state.get_run(run_id):
-            context.abort(grpc.StatusCode.NOT_FOUND, "Run ID not found")
+        if not run:
+            context.abort(grpc.StatusCode.NOT_FOUND, RUN_ID_NOT_FOUND_MESSAGE)
+
+        # If user auth is enabled, check if `flwr_aid` matches the run's `flwr_aid`
+        if self.auth_plugin:
+            flwr_aid = shared_account_info.get().flwr_aid
+            _check_flwr_aid_in_run(
+                flwr_aid=flwr_aid, run=cast(Run, run), context=context
+            )
 
         after_timestamp = request.after_timestamp + 1e-6
         while context.is_active():
@@ -119,7 +137,10 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
             # is returned at this point and the server ends the stream.
             run_status = state.get_run_status({run_id})[run_id]
             if run_status.status == Status.FINISHED:
-                log(INFO, "All logs for run ID `%s` returned", request.run_id)
+                log(INFO, "All logs for run ID `%s` returned", run_id)
+
+                # Delete objects of the run from the object store
+                self.objectstore_factory.store().delete_objects_in_run(run_id)
                 break
 
             time.sleep(LOG_STREAM_INTERVAL)  # Sleep briefly to avoid busy waiting
@@ -131,11 +152,44 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         log(INFO, "ExecServicer.List")
         state = self.linkstate_factory.state()
 
-        # Handle `flwr ls --runs`
+        # Build a set of run IDs for `flwr ls --runs`
         if not request.HasField("run_id"):
-            return _create_list_runs_response(state.get_run_ids(), state)
-        # Handle `flwr ls --run-id <run_id>`
-        return _create_list_runs_response({request.run_id}, state)
+            if self.auth_plugin:
+                # If no `run_id` is specified and user auth is enabled,
+                # return run IDs for the authenticated user
+                flwr_aid = shared_account_info.get().flwr_aid
+                if flwr_aid is None:
+                    context.abort(
+                        grpc.StatusCode.PERMISSION_DENIED,
+                        "️⛔️ User authentication is enabled, but `flwr_aid` is None",
+                    )
+                run_ids = state.get_run_ids(flwr_aid=flwr_aid)
+            else:
+                # If no `run_id` is specified and no user auth is enabled,
+                # return all run IDs
+                run_ids = state.get_run_ids(None)
+        # Build a set of run IDs for `flwr ls --run-id <run_id>`
+        else:
+            # Retrieve run ID and run
+            run_id = request.run_id
+            run = state.get_run(run_id)
+
+            # Exit if `run_id` not found
+            if not run:
+                context.abort(grpc.StatusCode.NOT_FOUND, RUN_ID_NOT_FOUND_MESSAGE)
+
+            # If user auth is enabled, check if `flwr_aid` matches the run's `flwr_aid`
+            if self.auth_plugin:
+                flwr_aid = shared_account_info.get().flwr_aid
+                _check_flwr_aid_in_run(
+                    flwr_aid=flwr_aid, run=cast(Run, run), context=context
+                )
+
+            run_ids = {run_id}
+
+        # Init the object store
+        store = self.objectstore_factory.store()
+        return _create_list_runs_response(run_ids, state, store)
 
     def StopRun(
         self, request: StopRunRequest, context: grpc.ServicerContext
@@ -144,30 +198,42 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         log(INFO, "ExecServicer.StopRun")
         state = self.linkstate_factory.state()
 
+        # Retrieve run ID and run
+        run_id = request.run_id
+        run = state.get_run(run_id)
+
         # Exit if `run_id` not found
-        if not state.get_run(request.run_id):
-            context.abort(
-                grpc.StatusCode.NOT_FOUND, f"Run ID {request.run_id} not found"
+        if not run:
+            context.abort(grpc.StatusCode.NOT_FOUND, RUN_ID_NOT_FOUND_MESSAGE)
+
+        # If user auth is enabled, check if `flwr_aid` matches the run's `flwr_aid`
+        if self.auth_plugin:
+            flwr_aid = shared_account_info.get().flwr_aid
+            _check_flwr_aid_in_run(
+                flwr_aid=flwr_aid, run=cast(Run, run), context=context
             )
 
-        run_status = state.get_run_status({request.run_id})[request.run_id]
+        run_status = state.get_run_status({run_id})[run_id]
         if run_status.status == Status.FINISHED:
             context.abort(
                 grpc.StatusCode.FAILED_PRECONDITION,
-                f"Run ID {request.run_id} is already finished",
+                f"Run ID {run_id} is already finished",
             )
 
         update_success = state.update_run_status(
-            run_id=request.run_id,
+            run_id=run_id,
             new_status=RunStatus(Status.FINISHED, SubStatus.STOPPED, ""),
         )
 
         if update_success:
-            message_ids: set[UUID] = state.get_message_ids_from_run_id(request.run_id)
+            message_ids: set[str] = state.get_message_ids_from_run_id(run_id)
 
             # Delete Messages and their replies for the `run_id`
             state.delete_messages(message_ids)
 
+            # Delete objects of the run from the object store
+            self.objectstore_factory.store().delete_objects_in_run(run_id)
+
         return StopRunResponse(success=update_success)
 
     def GetLoginDetails(
@@ -222,10 +288,46 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         )
 
 
-def _create_list_runs_response(run_ids: set[int], state: LinkState) -> ListRunsResponse:
+def _create_list_runs_response(
+    run_ids: set[int], state: LinkState, store: ObjectStore
+) -> ListRunsResponse:
     """Create response for `flwr ls --runs` and `flwr ls --run-id <run_id>`."""
-    run_dict = {run_id: state.get_run(run_id) for run_id in run_ids}
+    run_dict = {run_id: run for run_id in run_ids if (run := state.get_run(run_id))}
+
+    # Delete objects of finished runs from the object store
+    for run_id, run in run_dict.items():
+        if run.status.status == Status.FINISHED:
+            store.delete_objects_in_run(run_id)
+
     return ListRunsResponse(
-        run_dict={run_id: run_to_proto(run) for run_id, run in run_dict.items() if run},
+        run_dict={run_id: run_to_proto(run) for run_id, run in run_dict.items()},
         now=now().isoformat(),
     )
+
+
+def _check_flwr_aid_in_run(
+    flwr_aid: Optional[str], run: Run, context: grpc.ServicerContext
+) -> None:
+    """Guard clause to check if `flwr_aid` matches the run's `flwr_aid`."""
+    # `flwr_aid` must not be None. Abort if it is None.
+    if flwr_aid is None:
+        context.abort(
+            grpc.StatusCode.PERMISSION_DENIED,
+            "️⛔️ User authentication is enabled, but `flwr_aid` is None",
+        )
+
+    # `run.flwr_aid` must not be an empty string. Abort if it is empty.
+    run_flwr_aid = run.flwr_aid
+    if not run_flwr_aid:
+        context.abort(
+            grpc.StatusCode.PERMISSION_DENIED,
+            "⛔️ User authentication is enabled, but the run is not associated "
+            "with a `flwr_aid`.",
+        )
+
+    # Exit if `flwr_aid` does not match the run's `flwr_aid`
+    if run_flwr_aid != flwr_aid:
+        context.abort(
+            grpc.StatusCode.PERMISSION_DENIED,
+            "⛔️ Run ID does not belong to the user",
+        )

flwr/superexec/exec_user_auth_interceptor.py

@@ -16,12 +16,12 @@
 
 
 import contextvars
-from typing import Any, Callable, Union, cast
+from typing import Any, Callable, Union
 
 import grpc
 
-from flwr.common.auth_plugin import ExecAuthPlugin
-from flwr.common.typing import UserInfo
+from flwr.common.auth_plugin import ExecAuthPlugin, ExecAuthzPlugin
+from flwr.common.typing import AccountInfo
 from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
     GetAuthTokensRequest,
     GetAuthTokensResponse,
@@ -45,8 +45,8 @@ Response = Union[
 ]
 
 
-shared_user_info: contextvars.ContextVar[UserInfo] = contextvars.ContextVar(
-    "user_info", default=UserInfo(user_id=None, user_name=None)
+shared_account_info: contextvars.ContextVar[AccountInfo] = contextvars.ContextVar(
+    "account_info", default=AccountInfo(flwr_aid=None, account_name=None)
 )
 
 
@@ -56,8 +56,10 @@ class ExecUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
     def __init__(
         self,
         auth_plugin: ExecAuthPlugin,
+        authz_plugin: ExecAuthzPlugin,
     ):
         self.auth_plugin = auth_plugin
+        self.authz_plugin = authz_plugin
 
     def intercept_service(
         self,
@@ -91,17 +93,44 @@ class ExecUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
                 return call(request, context)  # type: ignore
 
             # For other requests, check if the user is authenticated
-            valid_tokens, user_info = self.auth_plugin.validate_tokens_in_metadata(
+            valid_tokens, account_info = self.auth_plugin.validate_tokens_in_metadata(
                 metadata
             )
             if valid_tokens:
+                if account_info is None:
+                    context.abort(
+                        grpc.StatusCode.UNAUTHENTICATED,
+                        "Tokens validated, but user info not found",
+                    )
+                    raise grpc.RpcError()
                 # Store user info in contextvars for authenticated users
-                shared_user_info.set(cast(UserInfo, user_info))
+                shared_account_info.set(account_info)
+                # Check if the user is authorized
+                if not self.authz_plugin.verify_user_authorization(account_info):
+                    context.abort(
+                        grpc.StatusCode.PERMISSION_DENIED, "User not authorized"
+                    )
+                    raise grpc.RpcError()
                 return call(request, context)  # type: ignore
 
             # If the user is not authenticated, refresh tokens
-            tokens = self.auth_plugin.refresh_tokens(context.invocation_metadata())
+            tokens, account_info = self.auth_plugin.refresh_tokens(metadata)
             if tokens is not None:
+                if account_info is None:
+                    context.abort(
+                        grpc.StatusCode.UNAUTHENTICATED,
+                        "Tokens refreshed, but user info not found",
+                    )
+                    raise grpc.RpcError()
+                # Store user info in contextvars for authenticated users
+                shared_account_info.set(account_info)
+                # Check if the user is authorized
+                if not self.authz_plugin.verify_user_authorization(account_info):
+                    context.abort(
+                        grpc.StatusCode.PERMISSION_DENIED, "User not authorized"
+                    )
+                    raise grpc.RpcError()
+
                 context.send_initial_metadata(tokens)
                 return call(request, context)  # type: ignore
 

flwr/superexec/executor.py

@@ -74,6 +74,7 @@ class Executor(ABC):
         fab_file: bytes,
         override_config: UserConfig,
         federation_options: ConfigRecord,
+        flwr_aid: Optional[str],
     ) -> Optional[int]:
         """Start a run using the given Flower FAB ID and version.
 
@@ -88,6 +89,9 @@ class Executor(ABC):
             The config overrides dict sent by the user (using `flwr run`).
         federation_options: ConfigRecord
             The federation options sent by the user (using `flwr run`).
+        flwr_aid : Optional[str]
+            The Flower Account ID of the user starting the run, if authentication is
+            enabled.
 
         Returns
         -------

flwr/superexec/simulation.py

@@ -77,6 +77,7 @@ class SimulationEngine(Executor):
         fab_file: bytes,
         override_config: UserConfig,
         federation_options: ConfigRecord,
+        flwr_aid: Optional[str],
     ) -> Optional[int]:
         """Start run using the Flower Simulation Engine."""
         try:
@@ -96,7 +97,12 @@ class SimulationEngine(Executor):
             fab_id, fab_version = get_fab_metadata(fab.content)
 
             run_id = self.linkstate.create_run(
-                fab_id, fab_version, fab_hash, override_config, federation_options
+                fab_id,
+                fab_version,
+                fab_hash,
+                override_config,
+                federation_options,
+                flwr_aid,
             )
 
             # Create an empty context for the Run

flwr/superlink/__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."""

flwr/{client/supernode → supernode}/__init__.py

@@ -13,10 +13,3 @@
 # limitations under the License.
 # ==============================================================================
 """Flower SuperNode."""
-
-
-from .app import run_supernode as run_supernode
-
-__all__ = [
-    "run_supernode",
-]

flwr/{client/nodestate/nodestate.py → supernode/cli/__init__.py}

@@ -12,20 +12,13 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Abstract base class NodeState."""
+"""Flower command line interface for SuperNode."""
 
 
-import abc
-from typing import Optional
+from .flower_supernode import flower_supernode
+from .flwr_clientapp import flwr_clientapp
 
-
-class NodeState(abc.ABC):
-    """Abstract NodeState."""
-
-    @abc.abstractmethod
-    def set_node_id(self, node_id: Optional[int]) -> None:
-        """Set the node ID."""
-
-    @abc.abstractmethod
-    def get_node_id(self) -> int:
-        """Get the node ID."""
+__all__ = [
+    "flower_supernode",
+    "flwr_clientapp",
+]

flwr/{client/supernode/app.py → supernode/cli/flower_supernode.py}

@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower SuperNode."""
+"""`flower-supernode` command."""
 
 
 import argparse
@@ -42,12 +42,10 @@ from flwr.common.constant import (
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.exit_handlers import register_exit_handlers
 from flwr.common.logger import log
+from flwr.supernode.start_client_internal import start_client_internal
 
-from ..app import start_client_internal
-from ..clientapp.utils import get_load_client_app_fn
 
-
-def run_supernode() -> None:
+def flower_supernode() -> None:
     """Run Flower SuperNode."""
     args = _parse_args_run_supernode().parse_args()
 
@@ -64,12 +62,6 @@ def run_supernode() -> None:
         )
 
     root_certificates = try_obtain_root_certificates(args, args.superlink)
-    load_fn = get_load_client_app_fn(
-        default_app_ref="",
-        app_path=None,
-        flwr_dir=args.flwr_dir,
-        multi_app=True,
-    )
     authentication_keys = _try_setup_client_authentication(args)
 
     log(DEBUG, "Isolation mode: %s", args.isolation)
@@ -82,7 +74,6 @@ def run_supernode() -> None:
 
     start_client_internal(
         server_address=args.superlink,
-        load_client_app_fn=load_fn,
         transport=args.transport,
         root_certificates=root_certificates,
         insecure=args.insecure,

flwr/supernode/cli/flwr_clientapp.py

@@ -0,0 +1,81 @@
+# Copyright 2025 Flower Labs GmbH. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ==============================================================================
+"""`flwr-clientapp` command."""
+
+
+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.exit import ExitCode, flwr_exit
+from flwr.common.logger import log
+from flwr.supernode.runtime.run_clientapp import run_clientapp
+
+
+def flwr_clientapp() -> None:
+    """Run process-isolated Flower ClientApp."""
+    args = _parse_args_run_flwr_clientapp().parse_args()
+    if not args.insecure:
+        flwr_exit(
+            ExitCode.COMMON_TLS_NOT_SUPPORTED,
+            "flwr-clientapp does not support TLS yet.",
+        )
+
+    log(INFO, "Start `flwr-clientapp` process")
+    log(
+        DEBUG,
+        "`flwr-clientapp` will attempt to connect to SuperNode's "
+        "ClientAppIo API at %s with token %s",
+        args.clientappio_api_address,
+        args.token,
+    )
+    run_clientapp(
+        clientappio_api_address=args.clientappio_api_address,
+        run_once=(args.token is not None),
+        token=args.token,
+        flwr_dir=args.flwr_dir,
+        certificates=None,
+        parent_pid=args.parent_pid,
+    )
+
+
+def _parse_args_run_flwr_clientapp() -> argparse.ArgumentParser:
+    """Parse flwr-clientapp command line arguments."""
+    parser = argparse.ArgumentParser(
+        description="Run a Flower ClientApp",
+    )
+    parser.add_argument(
+        "--clientappio-api-address",
+        default=CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS,
+        type=str,
+        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=int,
+        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.",
+    )
+    add_args_flwr_app_common(parser=parser)
+    return parser