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

flwr/superexec/exec_license_interceptor.py

@@ -0,0 +1,82 @@
+# 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 Exec API license interceptor."""
+
+
+from collections.abc import Iterator
+from typing import Any, Callable, Union
+
+import grpc
+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."""
+
+    def __init__(self, license_plugin: LicensePlugin) -> None:
+        """Initialize the interceptor with a license plugin."""
+        self.license_plugin = license_plugin
+
+    def intercept_service(
+        self,
+        continuation: Callable[[Any], Any],
+        handler_call_details: grpc.HandlerCallDetails,
+    ) -> grpc.RpcMethodHandler:
+        """Flower server interceptor license logic.
+
+        Intercept all unary-unary/unary-stream calls from users and check the license.
+        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/"):
+            return continuation(handler_call_details)
+
+        # One of the method handlers in
+        # `flwr.superexec.exec_servicer.ExecServicer`
+        method_handler: grpc.RpcMethodHandler = continuation(handler_call_details)
+        return self._generic_license_unary_method_handler(method_handler)
+
+    def _generic_license_unary_method_handler(
+        self, method_handler: grpc.RpcMethodHandler
+    ) -> grpc.RpcMethodHandler:
+        def _generic_method_handler(
+            request: GrpcMessage,
+            context: grpc.ServicerContext,
+        ) -> Union[GrpcMessage, Iterator[GrpcMessage]]:
+            """Handle the method call with license checking."""
+            call = method_handler.unary_unary or method_handler.unary_stream
+
+            if not self.license_plugin.check_license():
+                context.abort(
+                    grpc.StatusCode.PERMISSION_DENIED,
+                    "❗️ License check failed. Please contact the SuperLink "
+                    "administrator.",
+                )
+                raise grpc.RpcError()
+
+            return call(request, context)  # type: ignore
+
+        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/exec_servicer.py

@@ -25,6 +25,7 @@ import grpc
 from flwr.common import now
 from flwr.common.auth_plugin import ExecAuthPlugin
 from flwr.common.constant import (
+    FAB_MAX_SIZE,
     LOG_STREAM_INTERVAL,
     RUN_ID_NOT_FOUND_MESSAGE,
     Status,
@@ -52,8 +53,8 @@ from flwr.proto.exec_pb2 import (  # pylint: disable=E0611
     StreamLogsRequest,
     StreamLogsResponse,
 )
-from flwr.server.superlink.ffs.ffs_factory import FfsFactory
 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
@@ -84,6 +85,14 @@ class ExecServicer(exec_pb2_grpc.ExecServicer):
         """Create run ID."""
         log(INFO, "ExecServicer.StartRun")
 
+        if len(request.fab.content) > FAB_MAX_SIZE:
+            log(
+                ERROR,
+                "FAB size exceeds maximum allowed size of %d bytes.",
+                FAB_MAX_SIZE,
+            )
+            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,

flwr/superexec/exec_user_auth_interceptor.py

@@ -72,6 +72,10 @@ 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/"):
+            return continuation(handler_call_details)
+
         # One of the method handlers in
         # `flwr.superexec.exec_servicer.ExecServicer`
         method_handler: grpc.RpcMethodHandler = continuation(handler_call_details)
@@ -108,7 +112,9 @@ class ExecUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
                 # 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"
+                        grpc.StatusCode.PERMISSION_DENIED,
+                        "❗️ User not authorized. "
+                        "Please contact the SuperLink administrator.",
                     )
                     raise grpc.RpcError()
                 return call(request, context)  # type: ignore
@@ -127,7 +133,9 @@ class ExecUserAuthInterceptor(grpc.ServerInterceptor):  # type: ignore
                 # 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"
+                        grpc.StatusCode.PERMISSION_DENIED,
+                        "❗️ User not authorized. "
+                        "Please contact the SuperLink administrator.",
                     )
                     raise grpc.RpcError()
 

flwr/superexec/executor.py

@@ -22,8 +22,8 @@ from typing import Optional
 
 from flwr.common import ConfigRecord
 from flwr.common.typing import UserConfig
-from flwr.server.superlink.ffs.ffs_factory import FfsFactory
 from flwr.server.superlink.linkstate import LinkStateFactory
+from flwr.supercore.ffs import FfsFactory
 
 
 @dataclass

flwr/superexec/simulation.py

@@ -25,9 +25,8 @@ from flwr.cli.config_utils import get_fab_metadata
 from flwr.common import ConfigRecord, Context, RecordDict
 from flwr.common.logger import log
 from flwr.common.typing import Fab, UserConfig
-from flwr.server.superlink.ffs import Ffs
-from flwr.server.superlink.ffs.ffs_factory import FfsFactory
 from flwr.server.superlink.linkstate import LinkState, LinkStateFactory
+from flwr.supercore.ffs import Ffs, FfsFactory
 
 from .executor import Executor
 

flwr/supernode/cli/flower_supernode.py

@@ -40,7 +40,6 @@ from flwr.common.constant import (
     TRANSPORT_TYPE_REST,
 )
 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
 
@@ -66,12 +65,6 @@ def flower_supernode() -> None:
 
     log(DEBUG, "Isolation mode: %s", args.isolation)
 
-    # Register handlers for graceful shutdown
-    register_exit_handlers(
-        event_type=EventType.RUN_SUPERNODE_LEAVE,
-        exit_message="SuperNode terminated gracefully.",
-    )
-
     start_client_internal(
         server_address=args.superlink,
         transport=args.transport,

flwr/supernode/cli/flwr_clientapp.py

@@ -22,6 +22,7 @@ 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.supercore.utils import mask_string
 from flwr.supernode.runtime.run_clientapp import run_clientapp
 
 
@@ -40,11 +41,11 @@ def flwr_clientapp() -> None:
         "`flwr-clientapp` will attempt to connect to SuperNode's "
         "ClientAppIo API at %s with token %s",
         args.clientappio_api_address,
-        args.token,
+        mask_string(args.token) if args.token else "None",
     )
     run_clientapp(
         clientappio_api_address=args.clientappio_api_address,
-        run_once=(args.token is not None),
+        run_once=(args.token is not None) or args.run_once,
         token=args.token,
         flwr_dir=args.flwr_dir,
         certificates=None,
@@ -66,7 +67,7 @@ def _parse_args_run_flwr_clientapp() -> argparse.ArgumentParser:
     )
     parser.add_argument(
         "--token",
-        type=int,
+        type=str,
         required=False,
         help="Unique token generated by SuperNode for each ClientApp execution",
     )
@@ -77,5 +78,11 @@ def _parse_args_run_flwr_clientapp() -> argparse.ArgumentParser:
         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

@@ -51,8 +51,9 @@ class InMemoryNodeState(NodeState):  # pylint: disable=too-many-instance-attribu
         # Store run ID to Context mapping
         self.ctx_store: dict[int, Context] = {}
         self.lock_ctx_store = Lock()
-        # Store run ID to token mapping
+        # Store run ID to token mapping and token to run ID mapping
         self.token_store: dict[int, str] = {}
+        self.token_to_run_id: dict[str, int] = {}
         self.lock_token_store = Lock()
 
     def set_node_id(self, node_id: Optional[int]) -> None:
@@ -177,6 +178,7 @@ class InMemoryNodeState(NodeState):  # pylint: disable=too-many-instance-attribu
             if run_id in self.token_store:
                 raise ValueError("Token already created for this run ID")
             self.token_store[run_id] = token
+            self.token_to_run_id[token] = run_id
         return token
 
     def verify_token(self, run_id: int, token: str) -> bool:
@@ -187,4 +189,11 @@ class InMemoryNodeState(NodeState):  # pylint: disable=too-many-instance-attribu
     def delete_token(self, run_id: int) -> None:
         """Delete the token for the given run ID."""
         with self.lock_token_store:
-            self.token_store.pop(run_id, None)
+            token = self.token_store.pop(run_id, None)
+            if token is not None:
+                self.token_to_run_id.pop(token, None)
+
+    def get_run_id_by_token(self, token: str) -> Optional[int]:
+        """Get the run ID associated with a given token."""
+        with self.lock_token_store:
+            return self.token_to_run_id.get(token)

flwr/supernode/nodestate/nodestate.py

@@ -210,3 +210,18 @@ class NodeState(ABC):
         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.
+        """

flwr/supernode/runtime/run_clientapp.py

@@ -32,34 +32,54 @@ from flwr.common import Context, Message
 from flwr.common.config import get_flwr_dir
 from flwr.common.constant import ErrorCode
 from flwr.common.grpc import create_channel, on_channel_state_change
+from flwr.common.inflatable import (
+    get_all_nested_objects,
+    get_object_tree,
+    no_object_id_recompute,
+)
+from flwr.common.inflatable_protobuf_utils import (
+    make_confirm_message_received_fn_protobuf,
+    make_pull_object_fn_protobuf,
+    make_push_object_fn_protobuf,
+)
+from flwr.common.inflatable_utils import pull_and_inflate_object_from_tree, push_objects
 from flwr.common.logger import log
+from flwr.common.message import remove_content_from_message
 from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
 from flwr.common.serde import (
     context_from_proto,
     context_to_proto,
     fab_from_proto,
-    message_from_proto,
     message_to_proto,
     run_from_proto,
 )
 from flwr.common.typing import Fab, Run
+from flwr.proto.appio_pb2 import (  # pylint: disable=E0611
+    PullAppInputsRequest,
+    PullAppInputsResponse,
+    PullAppMessagesRequest,
+    PullAppMessagesResponse,
+    PushAppMessagesRequest,
+    PushAppOutputsRequest,
+    PushAppOutputsResponse,
+)
 
 # pylint: disable=E0611
 from flwr.proto.clientappio_pb2 import (
-    GetTokenRequest,
-    GetTokenResponse,
-    PullClientAppInputsRequest,
-    PullClientAppInputsResponse,
-    PushClientAppOutputsRequest,
-    PushClientAppOutputsResponse,
+    GetRunIdsWithPendingMessagesRequest,
+    GetRunIdsWithPendingMessagesResponse,
+    RequestTokenRequest,
+    RequestTokenResponse,
 )
 from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
+from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
+from flwr.supercore.utils import mask_string
 
 
 def run_clientapp(  # pylint: disable=R0913, R0914, R0917
     clientappio_api_address: str,
     run_once: bool,
-    token: Optional[int] = None,
+    token: Optional[str] = None,
     flwr_dir: Optional[str] = None,
     certificates: Optional[bytes] = None,
     parent_pid: Optional[int] = None,
@@ -84,9 +104,8 @@ def run_clientapp(  # pylint: disable=R0913, R0914, R0917
 
         while True:
             # If token is not set, loop until token is received from SuperNode
-            while token is None:
+            if token is None:
                 token = get_token(stub)
-                time.sleep(1)
 
             # Pull Message, Context, Run and (optional) FAB from SuperNode
             message, context, run, fab = pull_clientappinputs(stub=stub, token=token)
@@ -172,34 +191,58 @@ def start_parent_process_monitor(
     threading.Thread(target=monitor, daemon=True).start()
 
 
-def get_token(stub: grpc.Channel) -> Optional[int]:
+def get_token(stub: ClientAppIoStub) -> str:
     """Get a token from SuperNode."""
     log(DEBUG, "[flwr-clientapp] Request token")
-    try:
-        res: GetTokenResponse = stub.GetToken(GetTokenRequest())
-        log(DEBUG, "[GetToken] Received token: %s", res.token)
-        return res.token
-    except grpc.RpcError as e:
-        if e.code() == grpc.StatusCode.FAILED_PRECONDITION:  # pylint: disable=no-member
-            log(DEBUG, "[GetToken] No token available yet")
-        else:
-            log(ERROR, "[GetToken] gRPC error occurred: %s", str(e))
-        return None
+    while True:
+        res: GetRunIdsWithPendingMessagesResponse = stub.GetRunIdsWithPendingMessages(
+            GetRunIdsWithPendingMessagesRequest()
+        )
+
+        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: grpc.Channel, token: int
+    stub: ClientAppIoStub, token: str
 ) -> tuple[Message, Context, Run, Optional[Fab]]:
     """Pull ClientAppInputs from SuperNode."""
-    log(INFO, "[flwr-clientapp] Pull `ClientAppInputs` for token %s", token)
+    masked_token = mask_string(token)
+    log(INFO, "[flwr-clientapp] Pull `ClientAppInputs` for token %s", masked_token)
     try:
-        res: PullClientAppInputsResponse = stub.PullClientAppInputs(
-            PullClientAppInputsRequest(token=token)
+        # Pull Context, Run and (optional) FAB
+        res: PullAppInputsResponse = stub.PullClientAppInputs(
+            PullAppInputsRequest(token=token)
         )
-        message = message_from_proto(res.message)
         context = context_from_proto(res.context)
         run = run_from_proto(res.run)
         fab = fab_from_proto(res.fab) if res.fab else None
+
+        # Pull and inflate the message
+        pull_msg_res: PullAppMessagesResponse = stub.PullMessage(
+            PullAppMessagesRequest(token=token)
+        )
+        run_id = context.run_id
+        node = Node(node_id=context.node_id)
+        object_tree = pull_msg_res.message_object_trees[0]
+        message = pull_and_inflate_object_from_tree(
+            object_tree,
+            make_pull_object_fn_protobuf(stub.PullObject, node, run_id),
+            make_confirm_message_received_fn_protobuf(
+                stub.ConfirmMessageReceived, node, run_id
+            ),
+            return_type=Message,
+        )
+
+        # Set the message ID
+        # The deflated message doesn't contain the message_id (its own object_id)
+        message.metadata.__dict__["_message_id"] = object_tree.object_id
         return message, context, run, fab
     except grpc.RpcError as e:
         log(ERROR, "[PullClientAppInputs] gRPC error occurred: %s", str(e))
@@ -207,18 +250,52 @@ def pull_clientappinputs(
 
 
 def push_clientappoutputs(
-    stub: grpc.Channel, token: int, message: Message, context: Context
-) -> PushClientAppOutputsResponse:
+    stub: ClientAppIoStub, token: str, message: Message, context: Context
+) -> PushAppOutputsResponse:
     """Push ClientAppOutputs to SuperNode."""
-    log(INFO, "[flwr-clientapp] Push `ClientAppOutputs` for token %s", token)
-    proto_message = message_to_proto(message)
+    masked_token = mask_string(token)
+    log(INFO, "[flwr-clientapp] Push `ClientAppOutputs` for token %s", masked_token)
+    # Set message ID
+    message.metadata.__dict__["_message_id"] = message.object_id
+    proto_message = message_to_proto(remove_content_from_message(message))
     proto_context = context_to_proto(context)
 
     try:
-        res: PushClientAppOutputsResponse = stub.PushClientAppOutputs(
-            PushClientAppOutputsRequest(
-                token=token, message=proto_message, context=proto_context
+
+        with no_object_id_recompute():
+            # Get object tree and all objects to push
+            object_tree = get_object_tree(message)
+
+            # Push Message
+            # This is temporary. The message should not contain its content
+            push_msg_res = stub.PushMessage(
+                PushAppMessagesRequest(
+                    token=token,
+                    messages_list=[proto_message],
+                    message_object_trees=[object_tree],
+                )
             )
+            del proto_message
+
+            # Retrieve the object IDs to push
+            object_ids_to_push = set(push_msg_res.objects_to_push)
+
+            # Push all objects
+            all_objects = get_all_nested_objects(message)
+            del message
+            push_objects(
+                all_objects,
+                make_push_object_fn_protobuf(
+                    stub.PushObject,
+                    Node(node_id=context.node_id),
+                    run_id=context.run_id,
+                ),
+                object_ids_to_push=object_ids_to_push,
+            )
+
+        # Push Context
+        res: PushAppOutputsResponse = stub.PushClientAppOutputs(
+            PushAppOutputsRequest(token=token, context=proto_context)
         )
         return res
     except grpc.RpcError as e:

flwr/supernode/scheduler/__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 ClientApp Scheduler."""
+
+
+from .simple_clientapp_scheduler_plugin import SimpleClientAppSchedulerPlugin
+
+__all__ = [
+    "SimpleClientAppSchedulerPlugin",
+]

flwr/supernode/scheduler/simple_clientapp_scheduler_plugin.py

@@ -0,0 +1,49 @@
+# 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 ClientApp Scheduler plugin."""
+
+
+import os
+import subprocess
+from collections.abc import Sequence
+from typing import Optional
+
+from flwr.supercore.scheduler import SchedulerPlugin
+
+
+class SimpleClientAppSchedulerPlugin(SchedulerPlugin):
+    """Simple Flower ClientApp Scheduler plugin.
+
+    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)

flwr/supernode/servicer/clientappio/__init__.py

@@ -15,10 +15,8 @@
 """ClientAppIo API Servicer."""
 
 
-from .clientappio_servicer import ClientAppInputs, ClientAppIoServicer, ClientAppOutputs
+from .clientappio_servicer import ClientAppIoServicer
 
 __all__ = [
-    "ClientAppInputs",
     "ClientAppIoServicer",
-    "ClientAppOutputs",
 ]