flwr-nightly 1.14.0.dev20241204__py3-none-any.whl → 1.14.0.dev20241214__py3-none-any.whl

flwr/server/superlink/simulation/simulationio_servicer.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """SimulationIo API servicer."""
 
+
 import threading
 from logging import DEBUG, INFO
 
@@ -28,6 +29,7 @@ from flwr.common.serde import (
     context_to_proto,
     fab_to_proto,
     run_status_from_proto,
+    run_status_to_proto,
     run_to_proto,
 )
 from flwr.common.typing import Fab, RunStatus
@@ -39,6 +41,8 @@ from flwr.proto.log_pb2 import (  # pylint: disable=E0611
 from flwr.proto.run_pb2 import (  # pylint: disable=E0611
     GetFederationOptionsRequest,
     GetFederationOptionsResponse,
+    GetRunStatusRequest,
+    GetRunStatusResponse,
     UpdateRunStatusRequest,
     UpdateRunStatusResponse,
 )
@@ -122,6 +126,22 @@ class SimulationIoServicer(simulationio_pb2_grpc.SimulationIoServicer):
         )
         return UpdateRunStatusResponse()
 
+    def GetRunStatus(
+        self, request: GetRunStatusRequest, context: ServicerContext
+    ) -> GetRunStatusResponse:
+        """Get status of requested runs."""
+        log(DEBUG, "SimultionIoServicer.GetRunStatus")
+        state = self.state_factory.state()
+
+        statuses = state.get_run_status(set(request.run_ids))
+
+        return GetRunStatusResponse(
+            run_status_dict={
+                run_id: run_status_to_proto(status)
+                for run_id, status in statuses.items()
+            }
+        )
+
     def PushLogs(
         self, request: PushLogsRequest, context: grpc.ServicerContext
     ) -> PushLogsResponse:

flwr/server/superlink/utils.py

@@ -0,0 +1,65 @@
+# Copyright 2024 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.
+# ==============================================================================
+"""SuperLink utilities."""
+
+
+from typing import Union
+
+import grpc
+
+from flwr.common.constant import Status, SubStatus
+from flwr.common.typing import RunStatus
+from flwr.server.superlink.linkstate import LinkState
+
+_STATUS_TO_MSG = {
+    Status.PENDING: "Run is pending.",
+    Status.STARTING: "Run is starting.",
+    Status.RUNNING: "Run is running.",
+    Status.FINISHED: "Run is finished.",
+}
+
+
+def check_abort(
+    run_id: int,
+    abort_status_list: list[str],
+    state: LinkState,
+) -> Union[str, None]:
+    """Check if the status of the provided `run_id` is in `abort_status_list`."""
+    run_status: RunStatus = state.get_run_status({run_id})[run_id]
+
+    if run_status.status in abort_status_list:
+        msg = _STATUS_TO_MSG[run_status.status]
+        if run_status.sub_status == SubStatus.STOPPED:
+            msg += " Stopped by user."
+        return msg
+
+    return None
+
+
+def abort_grpc_context(msg: Union[str, None], context: grpc.ServicerContext) -> None:
+    """Abort context with statuscode PERMISSION_DENIED if `msg` is not None."""
+    if msg is not None:
+        context.abort(grpc.StatusCode.PERMISSION_DENIED, msg)
+
+
+def abort_if(
+    run_id: int,
+    abort_status_list: list[str],
+    state: LinkState,
+    context: grpc.ServicerContext,
+) -> None:
+    """Abort context if status of the provided `run_id` is in `abort_status_list`."""
+    msg = check_abort(run_id, abort_status_list, state)
+    abort_grpc_context(msg, context)

flwr/simulation/app.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower Simulation process."""
 
+
 import argparse
 import sys
 from logging import DEBUG, ERROR, INFO

flwr/simulation/ray_transport/ray_actor.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Ray-based Flower Actor and ActorPool implementation."""
 
+
 import threading
 from abc import ABC
 from logging import DEBUG, ERROR, WARNING

flwr/simulation/ray_transport/utils.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Utilities for Actors in the Virtual Client Engine."""
 
+
 import traceback
 import warnings
 from logging import ERROR

flwr/simulation/run_simulation.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower Simulation."""
 
+
 import argparse
 import asyncio
 import json

flwr/superexec/app.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Flower SuperExec app."""
 
+
 import argparse
 import sys
 from logging import INFO

flwr/superexec/deployment.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Deployment engine executor."""
 
+
 import hashlib
 from logging import ERROR, INFO
 from pathlib import Path

flwr/superexec/exec_grpc.py

@@ -14,18 +14,22 @@
 # ==============================================================================
 """SuperExec gRPC API."""
 
+
+from collections.abc import Sequence
 from logging import INFO
 from typing import Optional
 
 import grpc
 
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
+from flwr.common.auth_plugin import ExecAuthPlugin
 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.server.superlink.ffs.ffs_factory import FfsFactory
 from flwr.server.superlink.fleet.grpc_bidi.grpc_server import generic_create_grpc_server
 from flwr.server.superlink.linkstate import LinkStateFactory
+from flwr.superexec.exec_user_auth_interceptor import ExecUserAuthInterceptor
 
 from .exec_servicer import ExecServicer
 from .executor import Executor
@@ -39,6 +43,7 @@ def run_exec_api_grpc(
     ffs_factory: FfsFactory,
     certificates: Optional[tuple[bytes, bytes, bytes]],
     config: UserConfig,
+    auth_plugin: Optional[ExecAuthPlugin] = None,
 ) -> grpc.Server:
     """Run Exec API (gRPC, request-response)."""
     executor.set_config(config)
@@ -47,16 +52,29 @@ def run_exec_api_grpc(
         linkstate_factory=state_factory,
         ffs_factory=ffs_factory,
         executor=executor,
+        auth_plugin=auth_plugin,
     )
+    interceptors: Optional[Sequence[grpc.ServerInterceptor]] = None
+    if auth_plugin is not None:
+        interceptors = [ExecUserAuthInterceptor(auth_plugin)]
     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),
         server_address=address,
         max_message_length=GRPC_MAX_MESSAGE_LENGTH,
         certificates=certificates,
+        interceptors=interceptors,
     )
 
-    log(INFO, "Flower Deployment Engine: Starting Exec API on %s", address)
+    if auth_plugin is None:
+        log(INFO, "Flower Deployment Engine: Starting Exec API on %s", address)
+    else:
+        log(
+            INFO,
+            "Flower Deployment Engine: Starting Exec API with user "
+            "authentication on %s",
+            address,
+        )
     exec_grpc_server.start()
 
     return exec_grpc_server

flwr/superexec/exec_servicer.py

@@ -18,24 +18,33 @@
 import time
 from collections.abc import Generator
 from logging import ERROR, INFO
-from typing import Any
+from typing import Any, Optional
+from uuid import UUID
 
 import grpc
 
 from flwr.common import now
-from flwr.common.constant import LOG_STREAM_INTERVAL, Status
+from flwr.common.auth_plugin import ExecAuthPlugin
+from flwr.common.constant import LOG_STREAM_INTERVAL, Status, SubStatus
 from flwr.common.logger import log
 from flwr.common.serde import (
     configs_record_from_proto,
     run_to_proto,
     user_config_from_proto,
 )
+from flwr.common.typing import RunStatus
 from flwr.proto import exec_pb2_grpc  # pylint: disable=E0611
 from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    GetAuthTokensRequest,
+    GetAuthTokensResponse,
+    GetLoginDetailsRequest,
+    GetLoginDetailsResponse,
     ListRunsRequest,
     ListRunsResponse,
     StartRunRequest,
     StartRunResponse,
+    StopRunRequest,
+    StopRunResponse,
     StreamLogsRequest,
     StreamLogsResponse,
 )
@@ -53,11 +62,13 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         linkstate_factory: LinkStateFactory,
         ffs_factory: FfsFactory,
         executor: Executor,
+        auth_plugin: Optional[ExecAuthPlugin] = None,
     ) -> None:
         self.linkstate_factory = linkstate_factory
         self.ffs_factory = ffs_factory
         self.executor = executor
         self.executor.initialize(linkstate_factory, ffs_factory)
+        self.auth_plugin = auth_plugin
 
     def StartRun(
         self, request: StartRunRequest, context: grpc.ServicerContext
@@ -126,6 +137,69 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         # Handle `flwr ls --run-id <run_id>`
         return _create_list_runs_response({request.run_id}, state)
 
+    def StopRun(
+        self, request: StopRunRequest, context: grpc.ServicerContext
+    ) -> StopRunResponse:
+        """Stop a given run ID."""
+        log(INFO, "ExecServicer.StopRun")
+        state = self.linkstate_factory.state()
+
+        # 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"
+            )
+
+        run_status = state.get_run_status({request.run_id})[request.run_id]
+        if run_status.status == Status.FINISHED:
+            context.abort(
+                grpc.StatusCode.FAILED_PRECONDITION,
+                f"Run ID {request.run_id} is already finished",
+            )
+
+        update_success = state.update_run_status(
+            run_id=request.run_id,
+            new_status=RunStatus(Status.FINISHED, SubStatus.STOPPED, ""),
+        )
+
+        if update_success:
+            task_ids: set[UUID] = state.get_task_ids_from_run_id(request.run_id)
+
+            # Delete TaskIns and TaskRes for the `run_id`
+            state.delete_tasks(task_ids)
+
+        return StopRunResponse(success=update_success)
+
+    def GetLoginDetails(
+        self, request: GetLoginDetailsRequest, context: grpc.ServicerContext
+    ) -> GetLoginDetailsResponse:
+        """Start login."""
+        log(INFO, "ExecServicer.GetLoginDetails")
+        if self.auth_plugin is None:
+            context.abort(
+                grpc.StatusCode.UNIMPLEMENTED,
+                "ExecServicer initialized without user authentication",
+            )
+            raise grpc.RpcError()  # This line is unreachable
+        return GetLoginDetailsResponse(
+            login_details=self.auth_plugin.get_login_details()
+        )
+
+    def GetAuthTokens(
+        self, request: GetAuthTokensRequest, context: grpc.ServicerContext
+    ) -> GetAuthTokensResponse:
+        """Get auth token."""
+        log(INFO, "ExecServicer.GetAuthTokens")
+        if self.auth_plugin is None:
+            context.abort(
+                grpc.StatusCode.UNIMPLEMENTED,
+                "ExecServicer initialized without user authentication",
+            )
+            raise grpc.RpcError()  # This line is unreachable
+        return GetAuthTokensResponse(
+            auth_tokens=self.auth_plugin.get_auth_tokens(dict(request.auth_details))
+        )
+
 
 def _create_list_runs_response(run_ids: set[int], state: LinkState) -> ListRunsResponse:
     """Create response for `flwr ls --runs` and `flwr ls --run-id <run_id>`."""

flwr/superexec/exec_user_auth_interceptor.py

@@ -0,0 +1,101 @@
+# Copyright 2024 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 Exec API interceptor."""
+
+
+from typing import Any, Callable, Union
+
+import grpc
+
+from flwr.common.auth_plugin import ExecAuthPlugin
+from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
+    GetAuthTokensRequest,
+    GetAuthTokensResponse,
+    GetLoginDetailsRequest,
+    GetLoginDetailsResponse,
+    StartRunRequest,
+    StartRunResponse,
+    StreamLogsRequest,
+    StreamLogsResponse,
+)
+
+Request = Union[
+    StartRunRequest,
+    StreamLogsRequest,
+    GetLoginDetailsRequest,
+    GetAuthTokensRequest,
+]
+
+Response = Union[
+    StartRunResponse, StreamLogsResponse, GetLoginDetailsResponse, GetAuthTokensResponse
+]
+
+
+class ExecUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
+    """Exec API interceptor for user authentication."""
+
+    def __init__(
+        self,
+        auth_plugin: ExecAuthPlugin,
+    ):
+        self.auth_plugin = auth_plugin
+
+    def intercept_service(
+        self,
+        continuation: Callable[[Any], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> grpc.RpcMethodHandler:
+        """Flower server interceptor authentication logic.
+
+        Intercept all unary-unary/unary-stream calls from users and authenticate users
+        by validating auth metadata sent by the user. Continue RPC call if user is
+        authenticated, else, terminate RPC call by setting context to abort.
+        """
+        # One of the method handlers in
+        # `flwr.superexec.exec_servicer.ExecServicer`
+        method_handler: grpc.RpcMethodHandler = continuation(handler_call_details)
+        return self._generic_auth_unary_method_handler(method_handler)
+
+    def _generic_auth_unary_method_handler(
+        self, method_handler: grpc.RpcMethodHandler
+    ) -> grpc.RpcMethodHandler:
+        def _generic_method_handler(
+            request: Request,
+            context: grpc.ServicerContext,
+        ) -> Response:
+            call = method_handler.unary_unary or method_handler.unary_stream
+            metadata = context.invocation_metadata()
+            if isinstance(
+                request, (GetLoginDetailsRequest, GetAuthTokensRequest)
+            ) or self.auth_plugin.validate_tokens_in_metadata(metadata):
+                return call(request, context)  # type: ignore
+
+            tokens = self.auth_plugin.refresh_tokens(context.invocation_metadata())
+            if tokens is not None:
+                context.send_initial_metadata(tokens)
+                return call(request, context)  # type: ignore
+
+            context.abort(grpc.StatusCode.UNAUTHENTICATED, "Access denied")
+            raise grpc.RpcError()  # This line is unreachable
+
+        if method_handler.unary_unary:
+            message_handler = grpc.unary_unary_rpc_method_handler
+        else:
+            message_handler = grpc.unary_stream_rpc_method_handler
+        return message_handler(
+            _generic_method_handler,
+            request_deserializer=method_handler.request_deserializer,
+            response_serializer=method_handler.response_serializer,
+        )

flwr/superexec/executor.py

@@ -14,6 +14,7 @@
 # ==============================================================================
 """Execute and monitor a Flower run."""
 
+
 from abc import ABC, abstractmethod
 from dataclasses import dataclass, field
 from subprocess import Popen

{flwr_nightly-1.14.0.dev20241204.dist-info → flwr_nightly-1.14.0.dev20241214.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: flwr-nightly
-Version: 1.14.0.dev20241204
+Version: 1.14.0.dev20241214
 Summary: Flower: A Friendly Federated AI Framework
 Home-page: https://flower.ai
 License: Apache-2.0
@@ -39,8 +39,9 @@ Requires-Dist: numpy (>=1.26.0,<3.0.0)
 Requires-Dist: pathspec (>=0.12.1,<0.13.0)
 Requires-Dist: protobuf (>=4.25.2,<5.0.0)
 Requires-Dist: pycryptodome (>=3.18.0,<4.0.0)
+Requires-Dist: pyyaml (>=6.0.2,<7.0.0)
 Requires-Dist: ray (==2.10.0) ; (python_version >= "3.9" and python_version < "3.12") and (extra == "simulation")
-Requires-Dist: requests (>=2.31.0,<3.0.0) ; extra == "rest"
+Requires-Dist: requests (>=2.31.0,<3.0.0)
 Requires-Dist: rich (>=13.5.0,<14.0.0)
 Requires-Dist: starlette (>=0.31.0,<0.32.0) ; extra == "rest"
 Requires-Dist: tomli (>=2.0.1,<3.0.0)
@@ -101,23 +102,23 @@ Flower's goal is to make federated learning accessible to everyone. This series
 
 0. **What is Federated Learning?**
 
-   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/doc/source/tutorial-series-what-is-federated-learning.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/doc/source/tutorial-series-what-is-federated-learning.ipynb))
+   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/framework/docs/source/tutorial-series-what-is-federated-learning.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/framework/docs/source/tutorial-series-what-is-federated-learning.ipynb))
 
 1. **An Introduction to Federated Learning**
 
-   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/doc/source/tutorial-series-get-started-with-flower-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/doc/source/tutorial-series-get-started-with-flower-pytorch.ipynb))
+   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/framework/docs/source/tutorial-series-get-started-with-flower-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/framework/docs/source/tutorial-series-get-started-with-flower-pytorch.ipynb))
 
 2. **Using Strategies in Federated Learning**
 
-   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/doc/source/tutorial-series-use-a-federated-learning-strategy-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/doc/source/tutorial-series-use-a-federated-learning-strategy-pytorch.ipynb))
+   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/framework/docs/source/tutorial-series-use-a-federated-learning-strategy-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/framework/docs/source/tutorial-series-use-a-federated-learning-strategy-pytorch.ipynb))
 
 3. **Building Strategies for Federated Learning**
 
-   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/doc/source/tutorial-series-build-a-strategy-from-scratch-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/doc/source/tutorial-series-build-a-strategy-from-scratch-pytorch.ipynb))
+   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/framework/docs/source/tutorial-series-build-a-strategy-from-scratch-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/framework/docs/source/tutorial-series-build-a-strategy-from-scratch-pytorch.ipynb))
 
 4. **Custom Clients for Federated Learning**
 
-   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/doc/source/tutorial-series-customize-the-client-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/doc/source/tutorial-series-customize-the-client-pytorch.ipynb))
+   [![Open in Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/adap/flower/blob/main/doc/source/tutorial-series-customize-the-client-pytorch.ipynb) (or open the [Jupyter Notebook](https://github.com/adap/flower/blob/main/framework/docs/source/tutorial-series-customize-the-client-pytorch.ipynb))
 
 Stay tuned, more tutorials are coming soon. Topics include **Privacy and Security in Federated Learning**, and **Scaling Federated Learning**.