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

flwr/supercore/object_store/object_store_factory.py

@@ -0,0 +1,44 @@
+# 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.
+# ==============================================================================
+"""Factory class that creates ObjectStore instances."""
+
+
+from logging import DEBUG
+from typing import Optional
+
+from flwr.common.logger import log
+
+from .in_memory_object_store import InMemoryObjectStore
+from .object_store import ObjectStore
+
+
+class ObjectStoreFactory:
+    """Factory class that creates ObjectStore instances."""
+
+    def __init__(self) -> None:
+        self.store_instance: Optional[ObjectStore] = None
+
+    def store(self) -> ObjectStore:
+        """Return an ObjectStore instance and create it, if necessary.
+
+        Returns
+        -------
+        ObjectStore
+            An ObjectStore instance for storing objects by object_id.
+        """
+        if self.store_instance is None:
+            self.store_instance = InMemoryObjectStore()
+        log(DEBUG, "Using InMemoryObjectStore")
+        return self.store_instance

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/supercore/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 App Scheduler."""
+
+
+from .plugin import SchedulerPlugin
+
+__all__ = [
+    "SchedulerPlugin",
+]

flwr/supercore/scheduler/plugin.py

@@ -0,0 +1,71 @@
+# 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 SchedulerPlugin."""
+
+
+from abc import ABC, abstractmethod
+from collections.abc import Sequence
+from typing import Callable, Optional
+
+from flwr.common.typing import Run
+
+
+class SchedulerPlugin(ABC):
+    """Abstract base class for Scheduler plugins."""
+
+    def __init__(
+        self,
+        appio_api_address: str,
+        flwr_dir: str,
+        get_run: Callable[[int], Run],
+    ) -> None:
+        self.appio_api_address = appio_api_address
+        self.flwr_dir = flwr_dir
+        self.get_run = get_run
+
+    @abstractmethod
+    def select_run_id(self, candidate_run_ids: Sequence[int]) -> Optional[int]:
+        """Select a run ID to execute from a sequence of candidates.
+
+        A candidate run ID is one that has at least one pending message and is
+        not currently in progress (i.e., not associated with a token).
+
+        Parameters
+        ----------
+        candidate_run_ids : Sequence[int]
+            A sequence of candidate run IDs to choose from.
+
+        Returns
+        -------
+        Optional[int]
+            The selected run ID, or None if no suitable candidate is found.
+        """
+
+    @abstractmethod
+    def launch_app(self, token: str, run_id: int) -> None:
+        """Launch the application associated with a given run ID and token.
+
+        This method starts the application process using the given `token`.
+        The `run_id` is used solely for bookkeeping purposes, allowing any
+        scheduler implementation to associate this launch with a specific run.
+
+        Parameters
+        ----------
+        token : str
+            The token required to run the application.
+        run_id : int
+           The ID of the run associated with the token, used for tracking or
+           logging purposes.
+        """

flwr/{client/nodestate/nodestate.py → supercore/utils.py}

@@ -12,20 +12,21 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Abstract base class NodeState."""
+"""Utility functions for the infrastructure."""
 
 
-import abc
-from typing import Optional
+def mask_string(value: str, head: int = 4, tail: int = 4) -> str:
+    """Mask a string by preserving only the head and tail characters.
 
+    Mask a string for safe display by preserving the head and tail characters,
+    and replacing the middle with '...'. Useful for logging tokens, secrets,
+    or IDs without exposing sensitive data.
 
-class NodeState(abc.ABC):
-    """Abstract NodeState."""
-
-    @abc.abstractmethod
-    def set_node_id(self, node_id: Optional[int]) -> None:
-        """Set the node ID."""
-
-    @abc.abstractmethod
-    def get_node_id(self) -> int:
-        """Get the node ID."""
+    Notes
+    -----
+    If the string is shorter than the combined length of `head` and `tail`,
+    the original string is returned unchanged.
+    """
+    if len(value) <= head + tail:
+        return value
+    return f"{value[:head]}...{value[-tail:]}"

flwr/superexec/deployment.py

@@ -31,9 +31,8 @@ from flwr.common.constant import (
 )
 from flwr.common.logger import log
 from flwr.common.typing import Fab, RunStatus, 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
 
@@ -132,6 +131,7 @@ class DeploymentEngine(Executor):
         self,
         fab: Fab,
         override_config: UserConfig,
+        flwr_aid: Optional[str],
     ) -> int:
         fab_hash = self.ffs.put(fab.content, {})
         if fab_hash != fab.hash_str:
@@ -141,7 +141,7 @@ class DeploymentEngine(Executor):
         fab_id, fab_version = get_fab_metadata(fab.content)
 
         run_id = self.linkstate.create_run(
-            fab_id, fab_version, fab_hash, override_config, ConfigRecord()
+            fab_id, fab_version, fab_hash, override_config, ConfigRecord(), flwr_aid
         )
         return run_id
 
@@ -161,6 +161,7 @@ class DeploymentEngine(Executor):
         fab_file: bytes,
         override_config: UserConfig,
         federation_options: ConfigRecord,
+        flwr_aid: Optional[str],
     ) -> Optional[int]:
         """Start run using the Flower Deployment Engine."""
         run_id = None
@@ -168,7 +169,9 @@ class DeploymentEngine(Executor):
 
             # Call SuperLink to create run
             run_id = self._create_run(
-                Fab(hashlib.sha256(fab_file).hexdigest(), fab_file), override_config
+                Fab(hashlib.sha256(fab_file).hexdigest(), fab_file),
+                override_config,
+                flwr_aid,
             )
 
             # Register context for the Run

flwr/superexec/exec_event_log_interceptor.py

@@ -24,7 +24,7 @@ from google.protobuf.message import Message as GrpcMessage
 from flwr.common.event_log_plugin.event_log_plugin import EventLogWriterPlugin
 from flwr.common.typing import LogEntry
 
-from .exec_user_auth_interceptor import shared_user_info
+from .exec_user_auth_interceptor import shared_account_info
 
 
 class ExecEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
@@ -44,6 +44,10 @@ class ExecEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
         Continue RPC call if event logger is enabled on the SuperLink, 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)
@@ -62,7 +66,7 @@ class ExecEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
             log_entry = self.log_plugin.compose_log_before_event(
                 request=request,
                 context=context,
-                user_info=shared_user_info.get(),
+                account_info=shared_account_info.get(),
                 method_name=method_name,
             )
             self.log_plugin.write_log(log_entry)
@@ -81,7 +85,7 @@ class ExecEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
                     log_entry = self.log_plugin.compose_log_after_event(
                         request=request,
                         context=context,
-                        user_info=shared_user_info.get(),
+                        account_info=shared_account_info.get(),
                         method_name=method_name,
                         response=unary_response or error,
                     )
@@ -111,7 +115,7 @@ class ExecEventLogInterceptor(grpc.ServerInterceptor):  # type: ignore
                         log_entry = self.log_plugin.compose_log_after_event(
                             request=request,
                             context=context,
-                            user_info=shared_user_info.get(),
+                            account_info=shared_account_info.get(),
                             method_name=method_name,
                             response=stream_response or error,
                         )

flwr/superexec/exec_grpc.py

@@ -21,44 +21,64 @@ from typing import Optional
 import grpc
 
 from flwr.common import GRPC_MAX_MESSAGE_LENGTH
-from flwr.common.auth_plugin import ExecAuthPlugin
+from flwr.common.auth_plugin import ExecAuthPlugin, ExecAuthzPlugin
 from flwr.common.event_log_plugin import EventLogWriterPlugin
+from flwr.common.exit import ExitCode, flwr_exit
 from flwr.common.grpc import generic_create_grpc_server
 from flwr.common.logger import log
 from flwr.common.typing import UserConfig
 from flwr.proto.exec_pb2_grpc import add_ExecServicer_to_server
-from flwr.server.superlink.ffs.ffs_factory import FfsFactory
 from flwr.server.superlink.linkstate import LinkStateFactory
+from flwr.supercore.ffs import FfsFactory
+from flwr.supercore.license_plugin import LicensePlugin
+from flwr.supercore.object_store import ObjectStoreFactory
 from flwr.superexec.exec_event_log_interceptor import ExecEventLogInterceptor
+from flwr.superexec.exec_license_interceptor import ExecLicenseInterceptor
 from flwr.superexec.exec_user_auth_interceptor import ExecUserAuthInterceptor
 
 from .exec_servicer import ExecServicer
 from .executor import Executor
 
+try:
+    from flwr.ee import get_license_plugin
+except ImportError:
 
-# pylint: disable-next=too-many-arguments, too-many-positional-arguments
+    def get_license_plugin() -> Optional[LicensePlugin]:
+        """Return the license plugin."""
+
+
+# pylint: disable-next=too-many-arguments,too-many-positional-arguments,too-many-locals
 def run_exec_api_grpc(
     address: str,
     executor: Executor,
     state_factory: LinkStateFactory,
     ffs_factory: FfsFactory,
+    objectstore_factory: ObjectStoreFactory,
     certificates: Optional[tuple[bytes, bytes, bytes]],
     config: UserConfig,
     auth_plugin: Optional[ExecAuthPlugin] = None,
+    authz_plugin: Optional[ExecAuthzPlugin] = None,
     event_log_plugin: Optional[EventLogWriterPlugin] = None,
 ) -> grpc.Server:
     """Run Exec API (gRPC, request-response)."""
     executor.set_config(config)
 
+    license_plugin: Optional[LicensePlugin] = get_license_plugin()
+    if license_plugin and not license_plugin.check_license():
+        flwr_exit(ExitCode.SUPERLINK_LICENSE_INVALID)
+
     exec_servicer: grpc.Server = ExecServicer(
         linkstate_factory=state_factory,
         ffs_factory=ffs_factory,
+        objectstore_factory=objectstore_factory,
         executor=executor,
         auth_plugin=auth_plugin,
     )
     interceptors: list[grpc.ServerInterceptor] = []
-    if auth_plugin is not None:
-        interceptors.append(ExecUserAuthInterceptor(auth_plugin))
+    if license_plugin is not None:
+        interceptors.append(ExecLicenseInterceptor(license_plugin))
+    if auth_plugin is not None and authz_plugin is not None:
+        interceptors.append(ExecUserAuthInterceptor(auth_plugin, authz_plugin))
     # Event log interceptor must be added after user auth interceptor
     if event_log_plugin is not None:
         interceptors.append(ExecEventLogInterceptor(event_log_plugin))

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,
+        )