flwr-nightly 1.13.0.dev20241021__py3-none-any.whl → 1.13.0.dev20241111__py3-none-any.whl

flwr/client/clientapp/app.py

@@ -24,6 +24,8 @@ import grpc
 from flwr.cli.install import install_from_fab
 from flwr.client.client_app import ClientApp, LoadClientAppError
 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 ErrorCode
 from flwr.common.grpc import create_channel
 from flwr.common.logger import log
@@ -54,15 +56,13 @@ from .utils import get_load_client_app_fn
 
 def flwr_clientapp() -> None:
     """Run process-isolated Flower ClientApp."""
-    log(INFO, "Starting Flower ClientApp")
-
     parser = argparse.ArgumentParser(
         description="Run a Flower ClientApp",
     )
     parser.add_argument(
         "--supernode",
         type=str,
-        help="Address of SuperNode ClientAppIo gRPC servicer",
+        help="Address of SuperNode's ClientAppIo API",
     )
     parser.add_argument(
         "--token",
@@ -70,16 +70,24 @@ def flwr_clientapp() -> None:
         required=False,
         help="Unique token generated by SuperNode for each ClientApp execution",
     )
+    add_args_flwr_app_common(parser=parser)
     args = parser.parse_args()
 
+    log(INFO, "Starting Flower ClientApp")
+
     log(
         DEBUG,
-        "Staring isolated `ClientApp` connected to SuperNode ClientAppIo at %s "
+        "Starting isolated `ClientApp` connected to SuperNode's ClientAppIo API at %s "
         "with token %s",
         args.supernode,
         args.token,
     )
-    run_clientapp(supernode=args.supernode, token=args.token)
+    run_clientapp(
+        supernode=args.supernode,
+        run_once=(args.token is not None),
+        token=args.token,
+        flwr_dir=args.flwr_dir,
+    )
 
 
 def on_channel_state_change(channel_connectivity: str) -> None:
@@ -89,27 +97,23 @@ def on_channel_state_change(channel_connectivity: str) -> None:
 
 def run_clientapp(  # pylint: disable=R0914
     supernode: str,
+    run_once: bool,
     token: Optional[int] = None,
+    flwr_dir: Optional[str] = None,
 ) -> None:
-    """Run Flower ClientApp process.
-
-    Parameters
-    ----------
-    supernode : str
-        Address of SuperNode
-    token : Optional[int] (default: None)
-        Unique SuperNode token for ClientApp-SuperNode authentication
-    """
+    """Run Flower ClientApp process."""
     channel = create_channel(
         server_address=supernode,
         insecure=True,
     )
     channel.subscribe(on_channel_state_change)
 
+    # Resolve directory where FABs are installed
+    flwr_dir_ = get_flwr_dir(flwr_dir)
+
     try:
         stub = ClientAppIoStub(channel)
 
-        only_once = token is not None
         while True:
             # If token is not set, loop until token is received from SuperNode
             while token is None:
@@ -122,13 +126,13 @@ def run_clientapp(  # pylint: disable=R0914
             # Install FAB, if provided
             if fab:
                 log(DEBUG, "Flower ClientApp starts FAB installation.")
-                install_from_fab(fab.content, flwr_dir=None, skip_prompt=True)
+                install_from_fab(fab.content, flwr_dir=flwr_dir_, skip_prompt=True)
 
             load_client_app_fn = get_load_client_app_fn(
                 default_app_ref="",
                 app_path=None,
                 multi_app=True,
-                flwr_dir=None,
+                flwr_dir=str(flwr_dir_),
             )
 
             try:
@@ -170,7 +174,7 @@ def run_clientapp(  # pylint: disable=R0914
 
             # Stop the loop if `flwr-clientapp` is expected to process only a single
             # message
-            if only_once:
+            if run_once:
                 break
 
     except KeyboardInterrupt:

flwr/client/nodestate/__init__.py

@@ -0,0 +1,25 @@
+# Copyright 2024 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 NodeState."""
+
+from .in_memory_nodestate import InMemoryNodeState as InMemoryNodeState
+from .nodestate import NodeState as NodeState
+from .nodestate_factory import NodeStateFactory as NodeStateFactory
+
+__all__ = [
+    "InMemoryNodeState",
+    "NodeState",
+    "NodeStateFactory",
+]

flwr/client/nodestate/in_memory_nodestate.py

@@ -0,0 +1,38 @@
+# Copyright 2024 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."""
+
+
+from typing import Optional
+
+from flwr.client.nodestate.nodestate import NodeState
+
+
+class InMemoryNodeState(NodeState):
+    """In-memory NodeState implementation."""
+
+    def __init__(self) -> None:
+        # Store node_id
+        self.node_id: Optional[int] = None
+
+    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

flwr/client/nodestate/nodestate.py

@@ -0,0 +1,30 @@
+# Copyright 2024 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."""
+
+import abc
+from typing import Optional
+
+
+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."""

flwr/client/nodestate/nodestate_factory.py

@@ -0,0 +1,37 @@
+# Copyright 2024 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 NodeState instances."""
+
+import threading
+from typing import Optional
+
+from .in_memory_nodestate import InMemoryNodeState
+from .nodestate import NodeState
+
+
+class NodeStateFactory:
+    """Factory class that creates NodeState instances."""
+
+    def __init__(self) -> None:
+        self.state_instance: Optional[NodeState] = None
+        self.lock = threading.RLock()
+
+    def state(self) -> NodeState:
+        """Return a State instance and create it, if necessary."""
+        # Lock access to NodeStateFactory to prevent returning different instances
+        with self.lock:
+            if self.state_instance is None:
+                self.state_instance = InMemoryNodeState()
+            return self.state_instance

flwr/client/{node_state.py → run_info_store.py}

@@ -1,4 +1,4 @@
-# Copyright 2023 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2024 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.
@@ -12,7 +12,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 # ==============================================================================
-"""Node state."""
+"""Deprecated Run Info Store."""
 
 
 from dataclasses import dataclass
@@ -36,7 +36,7 @@ class RunInfo:
     initial_run_config: UserConfig
 
 
-class NodeState:
+class DeprecatedRunInfoStore:
     """State of a node where client nodes execute runs."""
 
     def __init__(
@@ -83,6 +83,7 @@ class NodeState:
             self.run_infos[run_id] = RunInfo(
                 initial_run_config=initial_run_config,
                 context=Context(
+                    run_id=run_id,
                     node_id=self.node_id,
                     node_config=self.node_config,
                     state=RecordSet(),

flwr/client/supernode/app.py

@@ -31,6 +31,8 @@ from flwr.common import EventType, event
 from flwr.common.config import parse_config_args
 from flwr.common.constant import (
     FLEET_API_GRPC_RERE_DEFAULT_ADDRESS,
+    ISOLATION_MODE_PROCESS,
+    ISOLATION_MODE_SUBPROCESS,
     TRANSPORT_TYPE_GRPC_ADAPTER,
     TRANSPORT_TYPE_GRPC_RERE,
     TRANSPORT_TYPE_REST,
@@ -38,11 +40,7 @@ from flwr.common.constant import (
 from flwr.common.exit_handlers import register_exit_handlers
 from flwr.common.logger import log, warn_deprecated_feature
 
-from ..app import (
-    ISOLATION_MODE_PROCESS,
-    ISOLATION_MODE_SUBPROCESS,
-    start_client_internal,
-)
+from ..app import start_client_internal
 from ..clientapp.utils import get_load_client_app_fn
 
 
@@ -200,10 +198,10 @@ def _parse_args_run_supernode() -> argparse.ArgumentParser:
             ISOLATION_MODE_SUBPROCESS,
             ISOLATION_MODE_PROCESS,
         ],
-        help="Isolation mode when running `ClientApp` (optional, possible values: "
-        "`subprocess`, `process`). By default, `ClientApp` runs in the same process "
+        help="Isolation mode when running a `ClientApp` (optional, possible values: "
+        "`subprocess`, `process`). By default, a `ClientApp` runs in the same process "
         "that executes the SuperNode. Use `subprocess` to configure SuperNode to run "
-        "`ClientApp` in a subprocess. Use `process` to indicate that a separate "
+        "a `ClientApp` in a subprocess. Use `process` to indicate that a separate "
         "independent process gets created outside of SuperNode.",
     )
     parser.add_argument(

flwr/common/args.py

@@ -0,0 +1,83 @@
+# Copyright 2024 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.
+# ==============================================================================
+"""Common Flower arguments."""
+
+import argparse
+import sys
+from logging import DEBUG, WARN
+from os.path import isfile
+from pathlib import Path
+from typing import Optional
+
+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(
+        "--flwr-dir",
+        default=None,
+        help="""The path containing installed Flower Apps.
+        By default, this value is equal to:
+
+            - `$FLWR_HOME/` if `$FLWR_HOME` is defined
+            - `$XDG_DATA_HOME/.flwr/` if `$XDG_DATA_HOME` is defined
+            - `$HOME/.flwr/` in all other cases
+        """,
+    )
+    parser.add_argument(
+        "--insecure",
+        action="store_true",
+        help="Run the server without HTTPS, regardless of whether certificate "
+        "paths are provided. By default, the server runs with HTTPS enabled. "
+        "Use this flag only if you understand the risks.",
+    )
+    parser.add_argument(
+        "--root-certificates",
+        metavar="ROOT_CERT",
+        type=str,
+        help="Specifies the path to the PEM-encoded root certificate file for "
+        "establishing secure HTTPS connections.",
+    )
+
+
+def try_obtain_certificates(
+    args: argparse.Namespace,
+) -> Optional[bytes]:
+    """Validate and return the root certificates."""
+    if args.insecure:
+        if args.root_certificates is not None:
+            sys.exit(
+                "Conflicting options: The '--insecure' flag disables HTTPS, "
+                "but '--root-certificates' was also specified. Please remove "
+                "the '--root-certificates' option when running in insecure mode, "
+                "or omit '--insecure' to use HTTPS."
+            )
+        log(
+            WARN,
+            "Option `--insecure` was set. Starting insecure HTTP channel.",
+        )
+        root_certificates = None
+    else:
+        # Load the certificates if provided, or load the system certificates
+        if not isfile(args.root_certificates):
+            sys.exit("Path argument `--root-certificates` does not point to a file.")
+        root_certificates = Path(args.root_certificates).read_bytes()
+        log(
+            DEBUG,
+            "Starting secure HTTPS channel with the following certificates: %s.",
+            args.root_certificates,
+        )
+    return root_certificates

flwr/common/config.py

@@ -22,6 +22,7 @@ from typing import Any, Optional, Union, cast, get_args
 import tomli
 
 from flwr.cli.config_utils import get_fab_config, validate_fields
+from flwr.common import ConfigsRecord
 from flwr.common.constant import (
     APP_DIR,
     FAB_CONFIG_FILE,
@@ -229,3 +230,12 @@ def get_metadata_from_config(config: dict[str, Any]) -> tuple[str, str]:
         config["project"]["version"],
         f"{config['tool']['flwr']['app']['publisher']}/{config['project']['name']}",
     )
+
+
+def user_config_to_configsrecord(config: UserConfig) -> ConfigsRecord:
+    """Construct a `ConfigsRecord` out of a `UserConfig`."""
+    c_record = ConfigsRecord()
+    for k, v in config.items():
+        c_record[k] = v
+
+    return c_record

flwr/common/constant.py

@@ -40,15 +40,15 @@ TRANSPORT_TYPES = [
 # Addresses
 # SuperNode
 CLIENTAPPIO_API_DEFAULT_ADDRESS = "0.0.0.0:9094"
-# SuperExec
-EXEC_API_DEFAULT_ADDRESS = "0.0.0.0:9093"
 # SuperLink
-DRIVER_API_DEFAULT_ADDRESS = "0.0.0.0:9091"
+SERVERAPPIO_API_DEFAULT_ADDRESS = "0.0.0.0:9091"
 FLEET_API_GRPC_RERE_DEFAULT_ADDRESS = "0.0.0.0:9092"
 FLEET_API_GRPC_BIDI_DEFAULT_ADDRESS = (
     "[::]:8080"  # IPv6 to keep start_server compatible
 )
-FLEET_API_REST_DEFAULT_ADDRESS = "0.0.0.0:9093"
+FLEET_API_REST_DEFAULT_ADDRESS = "0.0.0.0:9095"
+EXEC_API_DEFAULT_ADDRESS = "0.0.0.0:9093"
+SIMULATIONIO_API_DEFAULT_ADDRESS = "0.0.0.0:9096"
 
 # Constants for ping
 PING_DEFAULT_INTERVAL = 30
@@ -84,6 +84,16 @@ GRPC_ADAPTER_METADATA_MESSAGE_QUALNAME_KEY = "grpc-message-qualname"
 # Message TTL
 MESSAGE_TTL_TOLERANCE = 1e-1
 
+# Isolation modes
+ISOLATION_MODE_SUBPROCESS = "subprocess"
+ISOLATION_MODE_PROCESS = "process"
+
+# Log streaming configurations
+CONN_REFRESH_PERIOD = 60  # Stream connection refresh period
+CONN_RECONNECT_INTERVAL = 0.5  # Reconnect interval between two stream connections
+LOG_STREAM_INTERVAL = 0.5  # Log stream interval for `ExecServicer.StreamLogs`
+LOG_UPLOAD_INTERVAL = 0.2  # Minimum interval between two log uploads
+
 
 class MessageType:
     """Message type."""
@@ -124,8 +134,32 @@ class ErrorCode:
     UNKNOWN = 0
     LOAD_CLIENT_APP_EXCEPTION = 1
     CLIENT_APP_RAISED_EXCEPTION = 2
-    NODE_UNAVAILABLE = 3
 
     def __new__(cls) -> ErrorCode:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class Status:
+    """Run status."""
+
+    PENDING = "pending"
+    STARTING = "starting"
+    RUNNING = "running"
+    FINISHED = "finished"
+
+    def __new__(cls) -> Status:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class SubStatus:
+    """Run sub-status."""
+
+    COMPLETED = "completed"
+    FAILED = "failed"
+    STOPPED = "stopped"
+
+    def __new__(cls) -> SubStatus:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")

flwr/common/context.py

@@ -27,36 +27,41 @@ class Context:
 
     Parameters
     ----------
+    run_id : int
+        The ID that identifies the run.
     node_id : int
         The ID that identifies the node.
     node_config : UserConfig
         A config (key/value mapping) unique to the node and independent of the
         `run_config`. This config persists across all runs this node participates in.
     state : RecordSet
-        Holds records added by the entity in a given run and that will stay local.
+        Holds records added by the entity in a given `run_id` and that will stay local.
         This means that the data it holds will never leave the system it's running from.
         This can be used as an intermediate storage or scratchpad when
         executing mods. It can also be used as a memory to access
         at different points during the lifecycle of this entity (e.g. across
         multiple rounds)
     run_config : UserConfig
-        A config (key/value mapping) held by the entity in a given run and that will
-        stay local. It can be used at any point during the lifecycle of this entity
+        A config (key/value mapping) held by the entity in a given `run_id` and that
+        will stay local. It can be used at any point during the lifecycle of this entity
         (e.g. across multiple rounds)
     """
 
+    run_id: int
     node_id: int
     node_config: UserConfig
     state: RecordSet
     run_config: UserConfig
 
-    def __init__(  # pylint: disable=too-many-arguments
+    def __init__(  # pylint: disable=too-many-arguments, too-many-positional-arguments
         self,
+        run_id: int,
         node_id: int,
         node_config: UserConfig,
         state: RecordSet,
         run_config: UserConfig,
     ) -> None:
+        self.run_id = run_id
         self.node_id = node_id
         self.node_config = node_config
         self.state = state

flwr/common/date.py

@@ -15,9 +15,9 @@
 """Flower date utils."""
 
 
-from datetime import datetime, timezone
+import datetime
 
 
-def now() -> datetime:
+def now() -> datetime.datetime:
     """Construct a datetime from time.time() with time zone set to UTC."""
-    return datetime.now(tz=timezone.utc)
+    return datetime.datetime.now(tz=datetime.timezone.utc)

flwr/common/logger.py

@@ -16,9 +16,22 @@
 
 
 import logging
+import sys
+import threading
+import time
 from logging import WARN, LogRecord
 from logging.handlers import HTTPHandler
-from typing import TYPE_CHECKING, Any, Optional, TextIO
+from queue import Empty, Queue
+from typing import TYPE_CHECKING, Any, Optional, TextIO, Union
+
+import grpc
+
+from flwr.proto.log_pb2 import PushLogsRequest  # pylint: disable=E0611
+from flwr.proto.node_pb2 import Node  # pylint: disable=E0611
+from flwr.proto.serverappio_pb2_grpc import ServerAppIoStub  # pylint: disable=E0611
+from flwr.proto.simulationio_pb2_grpc import SimulationIoStub  # pylint: disable=E0611
+
+from .constant import LOG_UPLOAD_INTERVAL
 
 # Create logger
 LOGGER_NAME = "flwr"
@@ -259,3 +272,97 @@ def set_logger_propagation(
     if not child_logger.propagate:
         child_logger.log(logging.DEBUG, "Logger propagate set to False")
     return child_logger
+
+
+def mirror_output_to_queue(log_queue: Queue[Optional[str]]) -> None:
+    """Mirror stdout and stderr output to the provided queue."""
+
+    def get_write_fn(stream: TextIO) -> Any:
+        original_write = stream.write
+
+        def fn(s: str) -> int:
+            ret = original_write(s)
+            stream.flush()
+            log_queue.put(s)
+            return ret
+
+        return fn
+
+    sys.stdout.write = get_write_fn(sys.stdout)  # type: ignore[method-assign]
+    sys.stderr.write = get_write_fn(sys.stderr)  # type: ignore[method-assign]
+    console_handler.stream = sys.stdout
+
+
+def restore_output() -> None:
+    """Restore stdout and stderr.
+
+    This will stop mirroring output to queues.
+    """
+    sys.stdout = sys.__stdout__
+    sys.stderr = sys.__stderr__
+    console_handler.stream = sys.stdout
+
+
+def _log_uploader(
+    log_queue: Queue[Optional[str]], node_id: int, run_id: int, stub: ServerAppIoStub
+) -> None:
+    """Upload logs to the SuperLink."""
+    exit_flag = False
+    node = Node(node_id=node_id, anonymous=False)
+    msgs: list[str] = []
+    while True:
+        # Fetch all messages from the queue
+        try:
+            while True:
+                msg = log_queue.get_nowait()
+                # Quit the loops if the returned message is `None`
+                # This is a signal that the run has finished
+                if msg is None:
+                    exit_flag = True
+                    break
+                msgs.append(msg)
+        except Empty:
+            pass
+
+        # Upload if any logs
+        if msgs:
+            req = PushLogsRequest(
+                node=node,
+                run_id=run_id,
+                logs=msgs,
+            )
+            try:
+                stub.PushLogs(req)
+                msgs.clear()
+            except grpc.RpcError as e:
+                # Ignore minor network errors
+                # pylint: disable-next=no-member
+                if e.code() != grpc.StatusCode.UNAVAILABLE:
+                    raise e
+
+        if exit_flag:
+            break
+
+        time.sleep(LOG_UPLOAD_INTERVAL)
+
+
+def start_log_uploader(
+    log_queue: Queue[Optional[str]],
+    node_id: int,
+    run_id: int,
+    stub: Union[ServerAppIoStub, SimulationIoStub],
+) -> threading.Thread:
+    """Start the log uploader thread and return it."""
+    thread = threading.Thread(
+        target=_log_uploader, args=(log_queue, node_id, run_id, stub)
+    )
+    thread.start()
+    return thread
+
+
+def stop_log_uploader(
+    log_queue: Queue[Optional[str]], log_uploader: threading.Thread
+) -> None:
+    """Stop the log uploader thread."""
+    log_queue.put(None)
+    log_uploader.join()