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

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

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

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.

flwr/supernode/nodestate/in_memory_nodestate.py

@@ -0,0 +1,190 @@
+# 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.
+# ==============================================================================
+"""In-memory NodeState implementation."""
+
+
+import secrets
+from collections.abc import Sequence
+from dataclasses import dataclass
+from threading import Lock
+from typing import Optional
+
+from flwr.common import Context, Message
+from flwr.common.constant import FLWR_APP_TOKEN_LENGTH
+from flwr.common.typing import Run
+
+from .nodestate import NodeState
+
+
+@dataclass
+class MessageEntry:
+    """Data class to represent a message entry."""
+
+    message: Message
+    is_retrieved: bool = False
+
+
+class InMemoryNodeState(NodeState):  # pylint: disable=too-many-instance-attributes
+    """In-memory NodeState implementation."""
+
+    def __init__(self) -> None:
+        # Store node_id
+        self.node_id: Optional[int] = None
+        # Store Object ID to MessageEntry mapping
+        self.msg_store: dict[str, MessageEntry] = {}
+        self.lock_msg_store = Lock()
+        # Store run ID to Run mapping
+        self.run_store: dict[int, Run] = {}
+        self.lock_run_store = Lock()
+        # Store run ID to Context mapping
+        self.ctx_store: dict[int, Context] = {}
+        self.lock_ctx_store = Lock()
+        # Store run ID to token mapping
+        self.token_store: dict[int, str] = {}
+        self.lock_token_store = Lock()
+
+    def set_node_id(self, node_id: Optional[int]) -> None:
+        """Set the node ID."""
+        self.node_id = node_id
+
+    def get_node_id(self) -> int:
+        """Get the node ID."""
+        if self.node_id is None:
+            raise ValueError("Node ID not set")
+        return self.node_id
+
+    def store_message(self, message: Message) -> Optional[str]:
+        """Store a message."""
+        with self.lock_msg_store:
+            msg_id = message.metadata.message_id
+            if msg_id == "" or msg_id in self.msg_store:
+                return None
+            self.msg_store[msg_id] = MessageEntry(message=message)
+            return msg_id
+
+    def get_messages(
+        self,
+        *,
+        run_ids: Optional[Sequence[int]] = None,
+        is_reply: Optional[bool] = None,
+        limit: Optional[int] = None,
+    ) -> Sequence[Message]:
+        """Retrieve messages based on the specified filters."""
+        selected_messages: list[Message] = []
+
+        with self.lock_msg_store:
+            # Iterate through all messages in the store
+            for object_id in list(self.msg_store.keys()):
+                entry = self.msg_store[object_id]
+                message = entry.message
+
+                # Skip messages that have already been retrieved
+                if entry.is_retrieved:
+                    continue
+
+                # Skip messages whose run_id doesn't match the filter
+                if run_ids is not None:
+                    if message.metadata.run_id not in run_ids:
+                        continue
+
+                # If is_reply filter is set, filter for reply/non-reply messages
+                if is_reply is not None:
+                    is_reply_message = message.metadata.reply_to_message_id != ""
+                    # XOR logic to filter mismatched types (reply vs non-reply)
+                    if is_reply ^ is_reply_message:
+                        continue
+
+                # Add the message to the result set
+                selected_messages.append(message)
+
+                # Mark the message as retrieved
+                entry.is_retrieved = True
+
+                # Stop if the number of collected messages reaches the limit
+                if limit is not None and len(selected_messages) >= limit:
+                    break
+
+        return selected_messages
+
+    def delete_messages(
+        self,
+        *,
+        message_ids: Optional[Sequence[str]] = None,
+    ) -> None:
+        """Delete messages based on the specified filters."""
+        with self.lock_msg_store:
+            if message_ids is None:
+                # If no message IDs are provided, clear the entire store
+                self.msg_store.clear()
+                return
+
+            # Remove specified messages from the store
+            for msg_id in message_ids:
+                self.msg_store.pop(msg_id, None)
+
+    def store_run(self, run: Run) -> None:
+        """Store a run."""
+        with self.lock_run_store:
+            self.run_store[run.run_id] = run
+
+    def get_run(self, run_id: int) -> Optional[Run]:
+        """Retrieve a run by its ID."""
+        with self.lock_run_store:
+            return self.run_store.get(run_id)
+
+    def store_context(self, context: Context) -> None:
+        """Store a context."""
+        with self.lock_ctx_store:
+            self.ctx_store[context.run_id] = context
+
+    def get_context(self, run_id: int) -> Optional[Context]:
+        """Retrieve a context by its run ID."""
+        with self.lock_ctx_store:
+            return self.ctx_store.get(run_id)
+
+    def get_run_ids_with_pending_messages(self) -> Sequence[int]:
+        """Retrieve run IDs that have at least one pending message."""
+        # Collect run IDs from messages
+        with self.lock_msg_store:
+            ret = {
+                entry.message.metadata.run_id
+                for entry in self.msg_store.values()
+                if entry.message.metadata.reply_to_message_id == ""
+                and not entry.is_retrieved
+            }
+
+        # Remove run IDs that have tokens stored (indicating they are in progress)
+        with self.lock_token_store:
+            ret -= set(self.token_store.keys())
+            return list(ret)
+
+    def create_token(self, run_id: int) -> str:
+        """Create a token for the given run ID."""
+        token = secrets.token_hex(FLWR_APP_TOKEN_LENGTH)  # Generate a random token
+        with self.lock_token_store:
+            if run_id in self.token_store:
+                raise ValueError("Token already created for this run ID")
+            self.token_store[run_id] = token
+        return token
+
+    def verify_token(self, run_id: int, token: str) -> bool:
+        """Verify a token for the given run ID."""
+        with self.lock_token_store:
+            return self.token_store.get(run_id) == token
+
+    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)

flwr/supernode/nodestate/nodestate.py

@@ -0,0 +1,212 @@
+# 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.
+# ==============================================================================
+"""Abstract base class NodeState."""
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Optional
+
+from flwr.common import Context, Message
+from flwr.common.typing import Run
+
+
+class NodeState(ABC):
+    """Abstract base class for node state."""
+
+    @abstractmethod
+    def set_node_id(self, node_id: int) -> None:
+        """Set the node ID."""
+
+    @abstractmethod
+    def get_node_id(self) -> int:
+        """Get the node ID."""
+
+    @abstractmethod
+    def store_message(self, message: Message) -> Optional[str]:
+        """Store a message.
+
+        Parameters
+        ----------
+        message : Message
+            The message to store.
+
+        Returns
+        -------
+        Optional[str]
+            The object ID of the stored message, or None if storage failed.
+        """
+
+    @abstractmethod
+    def get_messages(
+        self,
+        *,
+        run_ids: Optional[Sequence[int]] = None,
+        is_reply: Optional[bool] = None,
+        limit: Optional[int] = None,
+    ) -> Sequence[Message]:
+        """Retrieve messages based on the specified filters.
+
+        If a filter is set to None, it is ignored.
+        If multiple filters are provided, they are combined using AND logic.
+
+        Parameters
+        ----------
+        run_ids : Optional[Sequence[int]] (default: None)
+            Sequence of run IDs to filter by. If a sequence is provided,
+            it is treated as an OR condition.
+        is_reply : Optional[bool] (default: None)
+            If True, filter for reply messages; if False, filter for non-reply
+            (instruction) messages.
+        limit : Optional[int] (default: None)
+            Maximum number of messages to return. If None, no limit is applied.
+
+        Returns
+        -------
+        Sequence[Message]
+            A sequence of messages matching the specified filters.
+
+        Notes
+        -----
+        **IMPORTANT:** Retrieved messages will **NOT** be returned again by subsequent
+        calls to this method, even if the filters match them.
+        """
+
+    @abstractmethod
+    def delete_messages(
+        self,
+        *,
+        message_ids: Optional[Sequence[str]] = None,
+    ) -> None:
+        """Delete messages based on the specified filters.
+
+        If a filter is set to None, it is ignored.
+        If multiple filters are provided, they are combined using AND logic.
+
+        Parameters
+        ----------
+        message_ids : Optional[Sequence[str]] (default: None)
+            Sequence of message (object) IDs to filter by. If a sequence is provided,
+            it is treated as an OR condition.
+
+        Notes
+        -----
+        **IMPORTANT:** **All messages** will be deleted if no filters are provided.
+        """
+
+    @abstractmethod
+    def store_run(self, run: Run) -> None:
+        """Store a run.
+
+        Parameters
+        ----------
+        run : Run
+            The `Run` instance to store.
+        """
+
+    @abstractmethod
+    def get_run(self, run_id: int) -> Optional[Run]:
+        """Retrieve a run by its ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run to retrieve.
+
+        Returns
+        -------
+        Optional[Run]
+            The `Run` instance if found, otherwise None.
+        """
+
+    @abstractmethod
+    def store_context(self, context: Context) -> None:
+        """Store a context.
+
+        Parameters
+        ----------
+        context : Context
+            The context to store.
+        """
+
+    @abstractmethod
+    def get_context(self, run_id: int) -> Optional[Context]:
+        """Retrieve a context by its run ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run with which the context is associated.
+
+        Returns
+        -------
+        Optional[Context]
+            The `Context` instance if found, otherwise None.
+        """
+
+    @abstractmethod
+    def get_run_ids_with_pending_messages(self) -> Sequence[int]:
+        """Retrieve run IDs that have at least one pending message.
+
+        Run IDs that are currently in progress (i.e., those associated with tokens)
+        will not be returned, even if they have pending messages.
+
+        Returns
+        -------
+        Sequence[int]
+            Sequence of run IDs with pending messages.
+        """
+
+    @abstractmethod
+    def create_token(self, run_id: int) -> str:
+        """Create a token for the given run ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run for which to create a token.
+
+        Returns
+        -------
+        str
+            A unique token associated with the run ID.
+        """
+
+    @abstractmethod
+    def verify_token(self, run_id: int, token: str) -> bool:
+        """Verify a token for the given run ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run for which to verify the token.
+        token : str
+            The token to verify.
+
+        Returns
+        -------
+        bool
+            True if the token is valid for the run ID, False otherwise.
+        """
+
+    @abstractmethod
+    def delete_token(self, run_id: int) -> None:
+        """Delete the token for the given run ID.
+
+        Parameters
+        ----------
+        run_id : int
+            The ID of the run for which to delete the token.
+        """

flwr/{client → supernode}/nodestate/nodestate_factory.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.

flwr/supernode/runtime/__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 SuperNode components."""

flwr/{client/clientapp/app.py → supernode/runtime/run_clientapp.py}

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.
@@ -15,24 +15,24 @@
 """Flower ClientApp process."""
 
 
-import argparse
 import gc
+import os
+import threading
 import time
 from logging import DEBUG, ERROR, INFO
 from typing import Optional
 
 import grpc
 
+from flwr.app.error import Error
 from flwr.cli.install import install_from_fab
 from flwr.client.client_app import ClientApp, LoadClientAppError
+from flwr.client.clientapp.utils import get_load_client_app_fn
 from flwr.common import Context, Message
-from flwr.common.args import add_args_flwr_app_common
 from flwr.common.config import get_flwr_dir
-from flwr.common.constant import CLIENTAPPIO_API_DEFAULT_CLIENT_ADDRESS, ErrorCode
-from flwr.common.exit import ExitCode, flwr_exit
+from flwr.common.constant import ErrorCode
 from flwr.common.grpc import create_channel, on_channel_state_change
 from flwr.common.logger import log
-from flwr.common.message import Error
 from flwr.common.retry_invoker import _make_simple_grpc_retry_invoker, _wrap_stub
 from flwr.common.serde import (
     context_from_proto,
@@ -55,43 +55,20 @@ from flwr.proto.clientappio_pb2 import (
 )
 from flwr.proto.clientappio_pb2_grpc import ClientAppIoStub
 
-from .utils import get_load_client_app_fn
 
-
-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,
-    )
-
-
-def run_clientapp(  # pylint: disable=R0914
+def run_clientapp(  # pylint: disable=R0913, R0914, R0917
     clientappio_api_address: str,
     run_once: bool,
     token: Optional[int] = None,
     flwr_dir: Optional[str] = None,
     certificates: Optional[bytes] = None,
+    parent_pid: Optional[int] = None,
 ) -> None:
     """Run Flower ClientApp process."""
+    # Monitor the main process in case of SIGKILL
+    if parent_pid is not None:
+        start_parent_process_monitor(parent_pid)
+
     channel = create_channel(
         server_address=clientappio_api_address,
         insecure=(certificates is None),
@@ -181,6 +158,20 @@ def run_clientapp(  # pylint: disable=R0914
         channel.close()
 
 
+def start_parent_process_monitor(
+    parent_pid: int,
+) -> None:
+    """Monitor the parent process and exit if it terminates."""
+
+    def monitor() -> None:
+        while True:
+            time.sleep(0.2)
+            if os.getppid() != parent_pid:
+                os.kill(os.getpid(), 9)
+
+    threading.Thread(target=monitor, daemon=True).start()
+
+
 def get_token(stub: grpc.Channel) -> Optional[int]:
     """Get a token from SuperNode."""
     log(DEBUG, "[flwr-clientapp] Request token")
@@ -233,25 +224,3 @@ def push_clientappoutputs(
     except grpc.RpcError as e:
         log(ERROR, "[PushClientAppOutputs] gRPC error occurred: %s", str(e))
         raise e
-
-
-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",
-    )
-    add_args_flwr_app_common(parser=parser)
-    return parser

flwr/supernode/servicer/__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 SuperNode servicers."""

flwr/supernode/servicer/clientappio/__init__.py

@@ -0,0 +1,24 @@
+# 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.
+# ==============================================================================
+"""ClientAppIo API Servicer."""
+
+
+from .clientappio_servicer import ClientAppInputs, ClientAppIoServicer, ClientAppOutputs
+
+__all__ = [
+    "ClientAppInputs",
+    "ClientAppIoServicer",
+    "ClientAppOutputs",
+]

flwr/{client/clientapp → supernode/servicer/clientappio}/clientappio_servicer.py

@@ -1,4 +1,4 @@
-# Copyright 2024 Flower Labs GmbH. All Rights Reserved.
+# 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.