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

flwr/supercore/corestate/__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 CoreState."""
+
+
+from .corestate import CoreState
+
+__all__ = [
+    "CoreState",
+]

flwr/supercore/corestate/corestate.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.
+# ==============================================================================
+"""Abstract base class CoreState."""
+
+
+from abc import ABC, abstractmethod
+from typing import Optional
+
+
+class CoreState(ABC):
+    """Abstract base class for core state."""
+
+    @abstractmethod
+    def create_token(self, run_id: int) -> Optional[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
+            The newly generated token if one does not already exist
+            for the given run ID, otherwise None.
+        """
+
+    @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.
+        """
+
+    @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/{server/superlink → supercore}/ffs/disk_ffs.py

@@ -20,7 +20,7 @@ import json
 from pathlib import Path
 from typing import Optional
 
-from flwr.server.superlink.ffs.ffs import Ffs
+from .ffs import Ffs
 
 
 class DiskFfs(Ffs):  # pylint: disable=R0904

flwr/supercore/grpc_health/__init__.py

@@ -0,0 +1,25 @@
+# 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.
+# ==============================================================================
+"""GRPC health servicers."""
+
+
+from .health_server import add_args_health, run_health_server_grpc_no_tls
+from .simple_health_servicer import SimpleHealthServicer
+
+__all__ = [
+    "SimpleHealthServicer",
+    "add_args_health",
+    "run_health_server_grpc_no_tls",
+]

flwr/supercore/grpc_health/health_server.py

@@ -0,0 +1,53 @@
+# 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.
+# ==============================================================================
+"""Health servers."""
+
+
+import argparse
+from logging import INFO
+
+import grpc
+from grpc_health.v1.health_pb2_grpc import add_HealthServicer_to_server
+
+from flwr.common.grpc import generic_create_grpc_server
+from flwr.common.logger import log
+
+from .simple_health_servicer import SimpleHealthServicer
+
+
+def run_health_server_grpc_no_tls(address: str) -> grpc.Server:
+    """Run gRPC health server with no TLS."""
+    health_server = generic_create_grpc_server(
+        servicer_and_add_fn=(
+            SimpleHealthServicer(),
+            add_HealthServicer_to_server,
+        ),
+        server_address=address,
+        certificates=None,
+    )
+    log(INFO, "Starting gRPC health server on %s", address)
+    health_server.start()
+    return health_server
+
+
+def add_args_health(parser: argparse.ArgumentParser) -> None:
+    """Add arguments for health server."""
+    parser.add_argument(
+        "--health-server-address",
+        type=str,
+        default=None,
+        help="Health service gRPC server address (IPv4, IPv6, or a domain name) "
+        "with no TLS. If not set, the health server will not be started.",
+    )

flwr/supercore/grpc_health/simple_health_servicer.py

@@ -0,0 +1,38 @@
+# 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 gRPC health servicers."""
+
+
+import grpc
+
+# pylint: disable=E0611
+from grpc_health.v1.health_pb2 import HealthCheckRequest, HealthCheckResponse
+from grpc_health.v1.health_pb2_grpc import HealthServicer
+
+# pylint: enable=E0611
+
+
+class SimpleHealthServicer(HealthServicer):  # type: ignore
+    """A simple gRPC health servicer that always returns SERVING."""
+
+    def Check(
+        self, request: HealthCheckRequest, context: grpc.ServicerContext
+    ) -> HealthCheckResponse:
+        """Return a HealthCheckResponse with SERVING status."""
+        return HealthCheckResponse(status=HealthCheckResponse.SERVING)
+
+    def Watch(self, request: HealthCheckRequest, context: grpc.ServicerContext) -> None:
+        """Watch the health status (not implemented)."""
+        context.abort(grpc.StatusCode.UNIMPLEMENTED, "Watch is not implemented")

flwr/supercore/license_plugin/__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 license plugin components."""
+
+
+from .license_plugin import LicensePlugin as LicensePlugin
+
+__all__ = [
+    "LicensePlugin",
+]

flwr/supercore/license_plugin/license_plugin.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.
+# ==============================================================================
+"""Abstract class for Flower License Plugin."""
+
+
+from abc import ABC, abstractmethod
+
+
+class LicensePlugin(ABC):
+    """Abstract Flower License Plugin class."""
+
+    @abstractmethod
+    def check_license(self) -> bool:
+        """Check if the license is valid."""

flwr/supercore/object_store/in_memory_object_store.py

@@ -20,7 +20,6 @@ from dataclasses import dataclass
 from typing import Optional
 
 from flwr.common.inflatable import (
-    get_object_children_ids_from_object_content,
     get_object_id,
     is_valid_sha256_hash,
     iterate_object_tree,
@@ -37,6 +36,7 @@ class ObjectEntry:
 
     content: bytes
     is_available: bool
+    child_object_ids: list[str]  # List of child object IDs
     ref_count: int  # Number of references (direct parents) to this object
     runs: set[int]  # Set of run IDs that used this object
 
@@ -70,6 +70,9 @@ class InMemoryObjectStore(ObjectStore):
                     self.store[obj_id] = ObjectEntry(
                         content=b"",  # Initially empty content
                         is_available=False,  # Initially not available
+                        child_object_ids=[  # List of child object IDs
+                            child.object_id for child in tree_node.children
+                        ],
                         ref_count=0,  # Reference count starts at 0
                         runs={run_id},  # Start with the current run ID
                     )
@@ -102,6 +105,32 @@ class InMemoryObjectStore(ObjectStore):
 
         return new_objects
 
+    def get_object_tree(self, object_id: str) -> ObjectTree:
+        """Get the object tree for a given object ID."""
+        with self.lock_store:
+            # Raise an exception if there's no object with the given ID
+            if not (object_entry := self.store.get(object_id)):
+                raise NoObjectInStoreError(
+                    f"Object with ID '{object_id}' was not pre-registered."
+                )
+
+            # Build the object trees of all children
+            try:
+                child_trees = [
+                    self.get_object_tree(child_id)
+                    for child_id in object_entry.child_object_ids
+                ]
+            except NoObjectInStoreError as e:
+                # Raise an error if any child object is missing
+                # This indicates an integrity issue
+                raise NoObjectInStoreError(
+                    f"Object tree for object ID '{object_id}' contains missing "
+                    "children. This may indicate a corrupted object store."
+                ) from e
+
+            # Create and return the ObjectTree for the current object
+            return ObjectTree(object_id=object_id, children=child_trees)
+
     def put(self, object_id: str, object_content: bytes) -> None:
         """Put an object into the store."""
         if self.verify:
@@ -128,29 +157,6 @@ class InMemoryObjectStore(ObjectStore):
             self.store[object_id].content = object_content
             self.store[object_id].is_available = True
 
-    def set_message_descendant_ids(
-        self, msg_object_id: str, descendant_ids: list[str]
-    ) -> None:
-        """Store the mapping from a ``Message`` object ID to the object IDs of its
-        descendants."""
-        with self.lock_msg_mapping:
-            self.msg_descendant_objects_mapping[msg_object_id] = descendant_ids
-
-    def get_message_descendant_ids(self, msg_object_id: str) -> list[str]:
-        """Retrieve the object IDs of all descendants of a given Message."""
-        with self.lock_msg_mapping:
-            if msg_object_id not in self.msg_descendant_objects_mapping:
-                raise NoObjectInStoreError(
-                    f"No message registered in Object Store with ID '{msg_object_id}'. "
-                    "Mapping to descendants could not be found."
-                )
-            return self.msg_descendant_objects_mapping[msg_object_id]
-
-    def delete_message_descendant_ids(self, msg_object_id: str) -> None:
-        """Delete the mapping from a ``Message`` object ID to its descendants."""
-        with self.lock_msg_mapping:
-            self.msg_descendant_objects_mapping.pop(msg_object_id, None)
-
     def get(self, object_id: str) -> Optional[bytes]:
         """Get an object from the store."""
         with self.lock_store:
@@ -177,10 +183,7 @@ class InMemoryObjectStore(ObjectStore):
                     self.run_objects_mapping[run_id].discard(object_id)
 
                 # Decrease the reference count of its children
-                children_ids = get_object_children_ids_from_object_content(
-                    object_entry.content
-                )
-                for child_id in children_ids:
+                for child_id in object_entry.child_object_ids:
                     self.store[child_id].ref_count -= 1
 
                     # Recursively try to delete the child object
@@ -205,9 +208,6 @@ class InMemoryObjectStore(ObjectStore):
                     # Delete the message object and its unreferenced descendants
                     self.delete(object_id)
 
-                    # Delete the message's descendants mapping
-                    self.delete_message_descendant_ids(object_id)
-
             # Remove the run from the mapping
             del self.run_objects_mapping[run_id]
 

flwr/supercore/object_store/object_store.py

@@ -60,6 +60,22 @@ class ObjectStore(abc.ABC):
             in the `ObjectStore`, or were preregistered but are not yet available.
         """
 
+    @abc.abstractmethod
+    def get_object_tree(self, object_id: str) -> ObjectTree:
+        """Get the object tree for a given object ID.
+
+        Parameters
+        ----------
+        object_id : str
+            The ID of the object for which to retrieve the object tree.
+
+        Returns
+        -------
+        ObjectTree
+            An ObjectTree representing the hierarchical structure of the object with
+            the given ID and its descendants.
+        """
+
     @abc.abstractmethod
     def put(self, object_id: str, object_content: bytes) -> None:
         """Put an object into the store.
@@ -83,8 +99,10 @@ class ObjectStore(abc.ABC):
 
         Returns
         -------
-        bytes
-            The object stored under the given object_id.
+        Optional[bytes]
+            The object stored under the given object_id if it exists, else None.
+            The returned bytes will be b"" if the object is not yet available,
+            but has been preregistered.
         """
 
     @abc.abstractmethod
@@ -126,46 +144,6 @@ class ObjectStore(abc.ABC):
         This method should remove all objects from the store.
         """
 
-    @abc.abstractmethod
-    def set_message_descendant_ids(
-        self, msg_object_id: str, descendant_ids: list[str]
-    ) -> None:
-        """Store the mapping from a ``Message`` object ID to the object IDs of its
-        descendants.
-
-        Parameters
-        ----------
-        msg_object_id : str
-            The object ID of the ``Message``.
-        descendant_ids : list[str]
-            A list of object IDs representing all descendant objects of the ``Message``.
-        """
-
-    @abc.abstractmethod
-    def get_message_descendant_ids(self, msg_object_id: str) -> list[str]:
-        """Retrieve the object IDs of all descendants of a given ``Message``.
-
-        Parameters
-        ----------
-        msg_object_id : str
-            The object ID of the ``Message``.
-
-        Returns
-        -------
-        list[str]
-            A list of object IDs of all descendant objects of the ``Message``.
-        """
-
-    @abc.abstractmethod
-    def delete_message_descendant_ids(self, msg_object_id: str) -> None:
-        """Delete the mapping from a ``Message`` object ID to its descendants.
-
-        Parameters
-        ----------
-        msg_object_id : str
-            The object ID of the ``Message``.
-        """
-
     @abc.abstractmethod
     def __contains__(self, object_id: str) -> bool:
         """Check if an object_id is in the store.

flwr/supercore/object_store/utils.py

@@ -0,0 +1,43 @@
+# 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.
+# ==============================================================================
+"""Utils for ObjectStore."""
+
+
+from typing import Union
+
+from flwr.proto.appio_pb2 import PushAppMessagesRequest  # pylint: disable=E0611
+from flwr.proto.fleet_pb2 import PushMessagesRequest  # pylint: disable=E0611
+
+from . import ObjectStore
+
+
+def store_mapping_and_register_objects(
+    store: ObjectStore, request: Union[PushAppMessagesRequest, PushMessagesRequest]
+) -> set[str]:
+    """Store Message object to descendants mapping and preregister objects."""
+    if not request.messages_list:
+        return set()
+    objects_to_push: set[str] = set()
+    # Get run_id from the first message in the list
+    # All messages of a request should in the same run
+    run_id = request.messages_list[0].metadata.run_id
+
+    for object_tree in request.message_object_trees:
+        # Preregister
+        unavailable_obj_ids = store.preregister(run_id, object_tree)
+        # Keep track of objects that need to be pushed
+        objects_to_push |= set(unavailable_obj_ids)
+
+    return objects_to_push

flwr/{superexec → supercore/superexec}/__init__.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Flower SuperExec service."""
+"""Flower SuperExec."""

flwr/supercore/superexec/plugin/__init__.py

@@ -0,0 +1,28 @@
+# 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 SuperExec plugins."""
+
+
+from .clientapp_exec_plugin import ClientAppExecPlugin
+from .exec_plugin import ExecPlugin
+from .serverapp_exec_plugin import ServerAppExecPlugin
+from .simulation_exec_plugin import SimulationExecPlugin
+
+__all__ = [
+    "ClientAppExecPlugin",
+    "ExecPlugin",
+    "ServerAppExecPlugin",
+    "SimulationExecPlugin",
+]

flwr/supercore/superexec/plugin/base_exec_plugin.py

@@ -0,0 +1,53 @@
+# 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 base Flower SuperExec plugin for app processes."""
+
+
+import os
+import subprocess
+from collections.abc import Sequence
+from typing import Optional
+
+from .exec_plugin import ExecPlugin
+
+
+class BaseExecPlugin(ExecPlugin):
+    """Simple Flower SuperExec plugin for app processes.
+
+    The plugin always selects the first candidate run ID.
+    """
+
+    # Placeholders to be defined in subclasses
+    command = ""
+    appio_api_address_arg = ""
+
+    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 = [self.command, "--insecure"]
+        cmds += [self.appio_api_address_arg, 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/supercore/superexec/plugin/clientapp_exec_plugin.py

@@ -0,0 +1,28 @@
+# 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 SuperExec plugin for ClientApp."""
+
+
+from .base_exec_plugin import BaseExecPlugin
+
+
+class ClientAppExecPlugin(BaseExecPlugin):
+    """Simple Flower SuperExec plugin for ClientApp.
+
+    The plugin always selects the first candidate run ID.
+    """
+
+    command = "flwr-clientapp"
+    appio_api_address_arg = "--clientappio-api-address"