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

flwr/client/rest_client/connection.py

@@ -14,40 +14,29 @@
 # ==============================================================================
 """Contextmanager for a REST request-response channel to the Flower server."""
 
+
 from collections.abc import Iterator
 from contextlib import contextmanager
-from copy import copy
-from logging import DEBUG, ERROR, INFO, WARN
-from typing import Callable, Optional, TypeVar, Union, cast
+from logging import ERROR, WARN
+from typing import Callable, Optional, TypeVar, Union
 
 from cryptography.hazmat.primitives.asymmetric import ec
 from google.protobuf.message import Message as GrpcMessage
 from requests.exceptions import ConnectionError as RequestsConnectionError
 
-from flwr.app.metadata import Metadata
-from flwr.client.message_handler.message_handler import validate_out_message
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
 from flwr.common.constant import HEARTBEAT_DEFAULT_INTERVAL
 from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.heartbeat import HeartbeatSender
-from flwr.common.inflatable import (
-    get_all_nested_objects,
-    get_object_tree,
-    no_object_id_recompute,
-)
-from flwr.common.inflatable_rest_utils import (
-    make_pull_object_fn_rest,
-    make_push_object_fn_rest,
-)
-from flwr.common.inflatable_utils import (
-    inflate_object_from_contents,
-    pull_objects,
-    push_objects,
+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.logger import log
 from flwr.common.message import Message, remove_content_from_message
 from flwr.common.retry_invoker import RetryInvoker
-from flwr.common.serde import message_to_proto, run_from_proto
+from flwr.common.serde import message_from_proto, message_to_proto, run_from_proto
 from flwr.common.typing import Fab, Run
 from flwr.proto.fab_pb2 import GetFabRequest, GetFabResponse  # pylint: disable=E0611
 from flwr.proto.fleet_pb2 import (  # pylint: disable=E0611
@@ -67,6 +56,7 @@ from flwr.proto.heartbeat_pb2 import (  # pylint: disable=E0611
 from flwr.proto.message_pb2 import (  # pylint: disable=E0611
     ConfirmMessageReceivedRequest,
     ConfirmMessageReceivedResponse,
+    ObjectTree,
     PullObjectRequest,
     PullObjectResponse,
     PushObjectRequest,
@@ -109,12 +99,15 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     ] = None,
 ) -> Iterator[
     tuple[
-        Callable[[], Optional[Message]],
-        Callable[[Message], None],
+        Callable[[], Optional[tuple[Message, ObjectTree]]],
+        Callable[[Message, ObjectTree], set[str]],
         Callable[[], Optional[int]],
         Callable[[], None],
         Callable[[int], Run],
         Callable[[str, int], Fab],
+        Callable[[int, str], bytes],
+        Callable[[int, str, bytes], None],
+        Callable[[int, str], None],
     ]
 ]:
     """Primitives for request/response-based interaction with a server.
@@ -150,6 +143,9 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
     create_node : Optional[Callable]
     delete_node : Optional[Callable]
     get_run : Optional[Callable]
+    pull_object : Callable[[str], bytes]
+    push_object : Callable[[str, bytes], None]
+    confirm_message_received : Callable[[str], None]
     """
     log(
         WARN,
@@ -178,9 +174,11 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         log(ERROR, "Client authentication is not supported for this transport type.")
 
     # Shared variables for inner functions
-    metadata: Optional[Metadata] = None
     node: Optional[Node] = None
 
+    # Remove should_giveup from RetryInvoker as REST does not support gRPC status codes
+    retry_invoker.should_giveup = None
+
     ###########################################################################
     # heartbeat/create_node/delete_node/receive/send/get_run functions
     ###########################################################################
@@ -232,6 +230,38 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         grpc_res.ParseFromString(res.content)
         return grpc_res
 
+    def _pull_object_protobuf(request: PullObjectRequest) -> PullObjectResponse:
+        res = _request(
+            req=request,
+            res_type=PullObjectResponse,
+            api_path=PATH_PULL_OBJECT,
+        )
+        if res is None:
+            raise ValueError(f"{PullObjectResponse.__name__} is None.")
+        return res
+
+    def _push_object_protobuf(request: PushObjectRequest) -> PushObjectResponse:
+        res = _request(
+            req=request,
+            res_type=PushObjectResponse,
+            api_path=PATH_PUSH_OBJECT,
+        )
+        if res is None:
+            raise ValueError(f"{PushObjectResponse.__name__} is None.")
+        return res
+
+    def _confirm_message_received_protobuf(
+        request: ConfirmMessageReceivedRequest,
+    ) -> ConfirmMessageReceivedResponse:
+        res = _request(
+            req=request,
+            res_type=ConfirmMessageReceivedResponse,
+            api_path=PATH_CONFIRM_MESSAGE_RECEIVED,
+        )
+        if res is None:
+            raise ValueError(f"{ConfirmMessageReceivedResponse.__name__} is None.")
+        return res
+
     def send_node_heartbeat() -> bool:
         # Get Node
         if node is None:
@@ -279,8 +309,7 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         """Set delete_node."""
         nonlocal node
         if node is None:
-            log(ERROR, "Node instance missing")
-            return
+            raise RuntimeError("Node instance missing")
 
         # Stop the heartbeat sender
         heartbeat_sender.stop()
@@ -296,162 +325,54 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
         # Cleanup
         node = None
 
-    def receive() -> Optional[Message]:
-        """Receive next Message from server."""
+    def receive() -> Optional[tuple[Message, ObjectTree]]:
+        """Pull a message with its ObjectTree from SuperLink."""
         # Get Node
         if node is None:
-            log(ERROR, "Node instance missing")
-            return None
+            raise RuntimeError("Node instance missing")
 
-        # Request instructions (message) from server
+        # Try to pull a message with its object tree from SuperLink
         req = PullMessagesRequest(node=node)
-
-        # Send the request
         res = _request(req, PullMessagesResponse, PATH_PULL_MESSAGES)
         if res is None:
-            return None
+            raise ValueError("PushMessagesResponse is None.")
 
-        # Get the current Messages
-        message_proto = None if len(res.messages_list) == 0 else res.messages_list[0]
+        # If no messages are available, return None
+        if len(res.messages_list) == 0:
+            return None
 
-        # Discard the current message if not valid
-        if message_proto is not None and not (
-            message_proto.metadata.dst_node_id == node.node_id
-        ):
-            message_proto = None
+        # Get the current Message and its object tree
+        message_proto = res.messages_list[0]
+        object_tree = res.message_object_trees[0]
 
         # Construct the Message
-        in_message: Optional[Message] = None
-
-        if message_proto:
-            log(INFO, "[Node] POST /%s: success", PATH_PULL_MESSAGES)
-            msg_id = message_proto.metadata.message_id
-            run_id = message_proto.metadata.run_id
-
-            def fn(request: PullObjectRequest) -> PullObjectResponse:
-                res = _request(
-                    req=request, res_type=PullObjectResponse, api_path=PATH_PULL_OBJECT
-                )
-                if res is None:
-                    raise ValueError("PushObjectResponse is None.")
-                return res
-
-            try:
-                all_object_contents = pull_objects(
-                    list(res.objects_to_pull[msg_id].object_ids) + [msg_id],
-                    pull_object_fn=make_pull_object_fn_rest(
-                        pull_object_rest=fn,
-                        node=node,
-                        run_id=run_id,
-                    ),
-                )
-
-                # Confirm that the message has been received
-                _request(
-                    req=ConfirmMessageReceivedRequest(
-                        node=node, run_id=run_id, message_object_id=msg_id
-                    ),
-                    res_type=ConfirmMessageReceivedResponse,
-                    api_path=PATH_CONFIRM_MESSAGE_RECEIVED,
-                )
-            except ValueError as e:
-                log(
-                    ERROR,
-                    "Pulling objects failed. Potential irrecoverable error: %s",
-                    str(e),
-                )
-            in_message = cast(
-                Message, inflate_object_from_contents(msg_id, all_object_contents)
-            )
-            # The deflated message doesn't contain the message_id (its own object_id)
-            # Inject
-            in_message.metadata.__dict__["_message_id"] = msg_id
-
-        # Remember `metadata` of the in message
-        nonlocal metadata
-        metadata = copy(in_message.metadata) if in_message else None
+        in_message = message_from_proto(message_proto)
 
-        return in_message
+        # Return the Message and its object tree
+        return in_message, object_tree
 
-    def send(message: Message) -> None:
-        """Send Message result back to server."""
+    def send(message: Message, object_tree: ObjectTree) -> set[str]:
+        """Send the message with its ObjectTree to SuperLink."""
         # Get Node
         if node is None:
-            log(ERROR, "Node instance missing")
-            return
+            raise RuntimeError("Node instance missing")
 
-        # Get incoming message
-        nonlocal metadata
-        if metadata is None:
-            log(ERROR, "No current message")
-            return
+        # Remove the content from the message if it has
+        if message.has_content():
+            message = remove_content_from_message(message)
 
-        # Set message_id
-        message.metadata.__dict__["_message_id"] = message.object_id
-        # Validate out message
-        if not validate_out_message(message, metadata):
-            log(ERROR, "Invalid out message")
-            return
-
-        with no_object_id_recompute():
-            # Get all nested objects
-            all_objects = get_all_nested_objects(message)
-            object_tree = get_object_tree(message)
-
-            # Serialize Message
-            message_proto = message_to_proto(
-                message=remove_content_from_message(message)
-            )
-            req = PushMessagesRequest(
-                node=node,
-                messages_list=[message_proto],
-                message_object_trees=[object_tree],
-            )
-
-            # Send the request
-            res = _request(req, PushMessagesResponse, PATH_PUSH_MESSAGES)
-            if res:
-                log(
-                    INFO,
-                    "[Node] POST /%s: success, created result %s",
-                    PATH_PUSH_MESSAGES,
-                    res.results,  # pylint: disable=no-member
-                )
-
-            if res and res.objects_to_push:
-                objs_to_push = set(res.objects_to_push[message.object_id].object_ids)
-
-                def fn(request: PushObjectRequest) -> PushObjectResponse:
-                    res = _request(
-                        req=request,
-                        res_type=PushObjectResponse,
-                        api_path=PATH_PUSH_OBJECT,
-                    )
-                    if res is None:
-                        raise ValueError("PushObjectResponse is None.")
-                    return res
-
-                try:
-                    push_objects(
-                        all_objects,
-                        push_object_fn=make_push_object_fn_rest(
-                            push_object_rest=fn,
-                            node=node,
-                            run_id=message_proto.metadata.run_id,
-                        ),
-                        object_ids_to_push=objs_to_push,
-                    )
-                    log(DEBUG, "Pushed %s objects to servicer.", len(objs_to_push))
-                except ValueError as e:
-                    log(
-                        ERROR,
-                        "Pushing objects failed. Potential irrecoverable error: %s",
-                        str(e),
-                    )
-                    log(ERROR, str(e))
+        # Send the message with its ObjectTree to SuperLink
+        req = PushMessagesRequest(
+            node=node,
+            messages_list=[message_to_proto(message)],
+            message_object_trees=[object_tree],
+        )
+        res = _request(req, PushMessagesResponse, PATH_PUSH_MESSAGES)
+        if res is None:
+            raise ValueError("PushMessagesResponse is None.")
 
-        # Cleanup
-        metadata = None
+        # Get and return the object IDs to push
+        return set(res.objects_to_push)
 
     def get_run(run_id: int) -> Run:
         # Construct the request
@@ -478,9 +399,58 @@ def http_request_response(  # pylint: disable=R0913,R0914,R0915,R0917
             res.fab.content,
         )
 
+    def pull_object(run_id: int, object_id: str) -> bytes:
+        """Pull the object from the SuperLink."""
+        # Check Node
+        if node is None:
+            raise RuntimeError("Node instance missing")
+
+        fn = make_pull_object_fn_protobuf(
+            pull_object_protobuf=_pull_object_protobuf,
+            node=node,
+            run_id=run_id,
+        )
+        return fn(object_id)
+
+    def push_object(run_id: int, object_id: str, contents: bytes) -> None:
+        """Push the object to the SuperLink."""
+        # Check Node
+        if node is None:
+            raise RuntimeError("Node instance missing")
+
+        fn = make_push_object_fn_protobuf(
+            push_object_protobuf=_push_object_protobuf,
+            node=node,
+            run_id=run_id,
+        )
+        fn(object_id, contents)
+
+    def confirm_message_received(run_id: int, object_id: str) -> None:
+        """Confirm that the message has been received."""
+        # Check Node
+        if node is None:
+            raise RuntimeError("Node instance missing")
+
+        fn = make_confirm_message_received_fn_protobuf(
+            confirm_message_received_protobuf=_confirm_message_received_protobuf,
+            node=node,
+            run_id=run_id,
+        )
+        fn(object_id)
+
     try:
         # Yield methods
-        yield (receive, send, create_node, delete_node, get_run, get_fab)
+        yield (
+            receive,
+            send,
+            create_node,
+            delete_node,
+            get_run,
+            get_fab,
+            pull_object,
+            push_object,
+            confirm_message_received,
+        )
     except Exception as exc:  # pylint: disable=broad-except
         log(ERROR, exc)
     # Cleanup

flwr/clientapp/__init__.py

@@ -13,3 +13,13 @@
 # limitations under the License.
 # ==============================================================================
 """Public Flower ClientApp APIs."""
+
+
+from flwr.client.client_app import ClientApp
+
+from . import mod
+
+__all__ = [
+    "ClientApp",
+    "mod",
+]

flwr/clientapp/mod/__init__.py

@@ -0,0 +1,26 @@
+# 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 Built-in Mods."""
+
+
+from flwr.client.mod.comms_mods import arrays_size_mod, message_size_mod
+
+from .centraldp_mods import fixedclipping_mod
+
+__all__ = [
+    "arrays_size_mod",
+    "fixedclipping_mod",
+    "message_size_mod",
+]

flwr/clientapp/mod/centraldp_mods.py

@@ -0,0 +1,132 @@
+# 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.
+# ==============================================================================
+"""Clipping modifiers for central DP with client-side clipping."""
+
+
+from collections import OrderedDict
+from logging import INFO, WARN
+from typing import cast
+
+from flwr.client.typing import ClientAppCallable
+from flwr.common import Array, ArrayRecord, Context, Message, MessageType, log
+from flwr.common.differential_privacy import compute_clip_model_update
+from flwr.common.differential_privacy_constants import KEY_CLIPPING_NORM
+
+
+# pylint: disable=too-many-return-statements
+def fixedclipping_mod(
+    msg: Message, ctxt: Context, call_next: ClientAppCallable
+) -> Message:
+    """Client-side fixed clipping modifier.
+
+    This mod needs to be used with the `DifferentialPrivacyClientSideFixedClipping`
+    server-side strategy wrapper.
+
+    The wrapper sends the clipping_norm value to the client.
+
+    This mod clips the client model updates before sending them to the server.
+
+    It operates on messages of type `MessageType.TRAIN`.
+
+    Notes
+    -----
+    Consider the order of mods when using multiple.
+
+    Typically, fixedclipping_mod should be the last to operate on params.
+    """
+    if msg.metadata.message_type != MessageType.TRAIN:
+        return call_next(msg, ctxt)
+
+    if len(msg.content.array_records) != 1:
+        log(
+            WARN,
+            "fixedclipping_mod is designed to work with a single ArrayRecord. "
+            "Skipping.",
+        )
+        return call_next(msg, ctxt)
+
+    if len(msg.content.config_records) != 1:
+        log(
+            WARN,
+            "fixedclipping_mod is designed to work with a single ConfigRecord. "
+            "Skipping.",
+        )
+        return call_next(msg, ctxt)
+
+    # Get keys in the single ConfigRecord
+    keys_in_config = set(next(iter(msg.content.config_records.values())).keys())
+    if KEY_CLIPPING_NORM not in keys_in_config:
+        raise KeyError(
+            f"The {KEY_CLIPPING_NORM} value is not supplied by the "
+            f"`DifferentialPrivacyClientSideFixedClipping` wrapper at"
+            f" the server side."
+        )
+    # Record array record communicated to client and clipping norm
+    original_array_record = next(iter(msg.content.array_records.values()))
+    clipping_norm = cast(
+        float, next(iter(msg.content.config_records.values()))[KEY_CLIPPING_NORM]
+    )
+
+    # Call inner app
+    out_msg = call_next(msg, ctxt)
+
+    # Check if the msg has error
+    if out_msg.has_error():
+        return out_msg
+
+    # Ensure there is a single ArrayRecord
+    if len(out_msg.content.array_records) != 1:
+        log(
+            WARN,
+            "fixedclipping_mod is designed to work with a single ArrayRecord. "
+            "Skipping.",
+        )
+        return out_msg
+
+    new_array_record_key, client_to_server_arrecord = next(
+        iter(out_msg.content.array_records.items())
+    )
+    # Ensure keys in returned ArrayRecord match those in the one sent from server
+    if set(original_array_record.keys()) != set(client_to_server_arrecord.keys()):
+        log(
+            WARN,
+            "fixedclipping_mod: Keys in ArrayRecord must match those from the model "
+            "that the ClientApp received. Skipping.",
+        )
+        return out_msg
+
+    client_to_server_ndarrays = client_to_server_arrecord.to_numpy_ndarrays()
+    # Clip the client update
+    compute_clip_model_update(
+        param1=client_to_server_ndarrays,
+        param2=original_array_record.to_numpy_ndarrays(),
+        clipping_norm=clipping_norm,
+    )
+
+    log(
+        INFO, "fixedclipping_mod: parameters are clipped by value: %.4f.", clipping_norm
+    )
+    # Replace outgoing ArrayRecord's Array while preserving their keys
+    out_msg.content.array_records[new_array_record_key] = ArrayRecord(
+        OrderedDict(
+            {
+                k: Array(v)
+                for k, v in zip(
+                    client_to_server_arrecord.keys(), client_to_server_ndarrays
+                )
+            }
+        )
+    )
+    return out_msg

flwr/common/args.py

@@ -17,7 +17,7 @@
 
 import argparse
 import sys
-from logging import DEBUG, ERROR, WARN
+from logging import DEBUG, ERROR, INFO, WARN
 from os.path import isfile
 from pathlib import Path
 from typing import Optional, Union
@@ -28,6 +28,12 @@ from flwr.common.logger import log
 
 def add_args_flwr_app_common(parser: argparse.ArgumentParser) -> None:
     """Add common Flower arguments for flwr-*app to the provided parser."""
+    parser.add_argument(
+        "--token",
+        type=str,
+        required=False,
+        help="Unique token generated by AppIo API for each app execution",
+    )
     parser.add_argument(
         "--flwr-dir",
         default=None,
@@ -47,6 +53,18 @@ def add_args_flwr_app_common(parser: argparse.ArgumentParser) -> None:
         "is not encrypted. By default, the server runs with HTTPS enabled. "
         "Use this flag only if you understand the risks.",
     )
+    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="This flag is deprecated and will be removed in a future release.",
+    )
 
 
 def try_obtain_root_certificates(
@@ -72,11 +90,7 @@ def try_obtain_root_certificates(
     else:
         # Load the certificates if provided, or load the system certificates
         if root_cert_path is None:
-            log(
-                WARN,
-                "Both `--insecure` and `--root-certificates` were not set. "
-                "Using system certificates.",
-            )
+            log(INFO, "Using system certificates")
             root_certificates = None
         elif not isfile(root_cert_path):
             log(ERROR, "Path argument `--root-certificates` does not point to a file.")

flwr/common/auth_plugin/__init__.py

@@ -16,11 +16,11 @@
 
 
 from .auth_plugin import CliAuthPlugin as CliAuthPlugin
-from .auth_plugin import ExecAuthPlugin as ExecAuthPlugin
-from .auth_plugin import ExecAuthzPlugin as ExecAuthzPlugin
+from .auth_plugin import ControlAuthPlugin as ControlAuthPlugin
+from .auth_plugin import ControlAuthzPlugin as ControlAuthzPlugin
 
 __all__ = [
     "CliAuthPlugin",
-    "ExecAuthPlugin",
-    "ExecAuthzPlugin",
+    "ControlAuthPlugin",
+    "ControlAuthzPlugin",
 ]

flwr/common/auth_plugin/auth_plugin.py

@@ -21,13 +21,13 @@ from pathlib import Path
 from typing import Optional, Union
 
 from flwr.common.typing import AccountInfo
-from flwr.proto.exec_pb2_grpc import ExecStub
+from flwr.proto.control_pb2_grpc import ControlStub
 
 from ..typing import UserAuthCredentials, UserAuthLoginDetails
 
 
-class ExecAuthPlugin(ABC):
-    """Abstract Flower Auth Plugin class for ExecServicer.
+class ControlAuthPlugin(ABC):
+    """Abstract Flower Auth Plugin class for ControlServicer.
 
     Parameters
     ----------
@@ -69,8 +69,8 @@ class ExecAuthPlugin(ABC):
         """Refresh authentication tokens in the provided metadata."""
 
 
-class ExecAuthzPlugin(ABC):  # pylint: disable=too-few-public-methods
-    """Abstract Flower Authorization Plugin class for ExecServicer.
+class ControlAuthzPlugin(ABC):  # pylint: disable=too-few-public-methods
+    """Abstract Flower Authorization Plugin class for ControlServicer.
 
     Parameters
     ----------
@@ -103,7 +103,7 @@ class CliAuthPlugin(ABC):
     @abstractmethod
     def login(
         login_details: UserAuthLoginDetails,
-        exec_stub: ExecStub,
+        control_stub: ControlStub,
     ) -> UserAuthCredentials:
         """Authenticate the user and retrieve authentication credentials.
 
@@ -111,7 +111,7 @@ class CliAuthPlugin(ABC):
         ----------
         login_details : UserAuthLoginDetails
             An object containing the user's login details.
-        exec_stub : ExecStub
+        control_stub : ControlStub
             A stub for executing RPC calls to the server.
 
         Returns