flwr-nightly 1.8.0.dev20240315__py3-none-any.whl → 1.15.0.dev20250115__py3-none-any.whl

flwr/common/context.py

@@ -18,21 +18,51 @@
 from dataclasses import dataclass
 
 from .record import RecordSet
+from .typing import UserConfig
 
 
 @dataclass
 class Context:
-    """State of your run.
+    """Context of your run.
 
     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_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, 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
+        self.run_config = run_config

flwr/common/date.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2023 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,9 +15,27 @@
 """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)
+
+
+def format_timedelta(td: datetime.timedelta) -> str:
+    """Format a timedelta as a string."""
+    days = td.days
+    hours, remainder = divmod(td.seconds, 3600)
+    minutes, seconds = divmod(remainder, 60)
+
+    if days > 0:
+        return f"{days}d {hours:02}:{minutes:02}:{seconds:02}"
+    return f"{hours:02}:{minutes:02}:{seconds:02}"
+
+
+def isoformat8601_utc(dt: datetime.datetime) -> str:
+    """Return the datetime formatted as an ISO 8601 string with a trailing 'Z'."""
+    if dt.tzinfo != datetime.timezone.utc:
+        raise ValueError("Expected datetime with timezone set to UTC")
+    return dt.isoformat(timespec="seconds").replace("+00:00", "Z")

flwr/common/differential_privacy.py

@@ -16,7 +16,7 @@
 
 
 from logging import WARNING
-from typing import Optional, Tuple
+from typing import Optional
 
 import numpy as np
 
@@ -125,7 +125,7 @@ def compute_adaptive_noise_params(
     noise_multiplier: float,
     num_sampled_clients: float,
     clipped_count_stddev: Optional[float],
-) -> Tuple[float, float]:
+) -> tuple[float, float]:
     """Compute noising parameters for the adaptive clipping.
 
     Paper: https://arxiv.org/abs/1905.03871

flwr/common/dp.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2022 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,8 +15,6 @@
 """Building block functions for DP algorithms."""
 
 
-from typing import Tuple
-
 import numpy as np
 
 from flwr.common.logger import warn_deprecated_feature
@@ -41,7 +39,7 @@ def add_gaussian_noise(update: NDArrays, std_dev: float) -> NDArrays:
     return update_noised
 
 
-def clip_by_l2(update: NDArrays, threshold: float) -> Tuple[NDArrays, bool]:
+def clip_by_l2(update: NDArrays, threshold: float) -> tuple[NDArrays, bool]:
     """Scales the update so thats its L2 norm is upper-bound to threshold."""
     warn_deprecated_feature("`clip_by_l2` method")
     update_norm = _get_update_norm(update)

flwr/common/exit_handlers.py

@@ -19,7 +19,7 @@ import sys
 from signal import SIGINT, SIGTERM, signal
 from threading import Thread
 from types import FrameType
-from typing import List, Optional
+from typing import Optional
 
 from grpc import Server
 
@@ -28,8 +28,8 @@ from flwr.common.telemetry import EventType, event
 
 def register_exit_handlers(
     event_type: EventType,
-    grpc_servers: Optional[List[Server]] = None,
-    bckg_threads: Optional[List[Thread]] = None,
+    grpc_servers: Optional[list[Server]] = None,
+    bckg_threads: Optional[list[Thread]] = None,
 ) -> None:
     """Register exit handlers for `SIGINT` and `SIGTERM` signals.
 

flwr/common/grpc.py

@@ -1,4 +1,4 @@
-# Copyright 2020 Flower Labs GmbH. All Rights Reserved.
+# Copyright 2022 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,21 +15,33 @@
 """Utility functions for gRPC."""
 
 
-from logging import DEBUG
-from typing import Optional
+import concurrent.futures
+import sys
+from collections.abc import Sequence
+from logging import DEBUG, ERROR
+from typing import Any, Callable, Optional
 
 import grpc
 
-from flwr.common.logger import log
+from .address import is_port_in_use
+from .logger import log
 
 GRPC_MAX_MESSAGE_LENGTH: int = 536_870_912  # == 512 * 1024 * 1024
 
+INVALID_CERTIFICATES_ERR_MSG = """
+    When setting any of root_certificate, certificate, or private_key,
+    all of them need to be set.
+"""
+
+AddServicerToServerFn = Callable[..., Any]
+
 
 def create_channel(
     server_address: str,
     insecure: bool,
     root_certificates: Optional[bytes] = None,
     max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,
+    interceptors: Optional[Sequence[grpc.UnaryUnaryClientInterceptor]] = None,
 ) -> grpc.Channel:
     """Create a gRPC channel, either secure or insecure."""
     # Check for conflicting parameters
@@ -51,10 +63,157 @@ def create_channel(
         channel = grpc.insecure_channel(server_address, options=channel_options)
         log(DEBUG, "Opened insecure gRPC connection (no certificates were passed)")
     else:
-        ssl_channel_credentials = grpc.ssl_channel_credentials(root_certificates)
+        try:
+            ssl_channel_credentials = grpc.ssl_channel_credentials(root_certificates)
+        except Exception as e:
+            raise ValueError(f"Failed to create SSL channel credentials: {e}") from e
         channel = grpc.secure_channel(
             server_address, ssl_channel_credentials, options=channel_options
         )
         log(DEBUG, "Opened secure gRPC connection using certificates")
 
+    if interceptors is not None:
+        channel = grpc.intercept_channel(channel, interceptors)
+
     return channel
+
+
+def valid_certificates(certificates: tuple[bytes, bytes, bytes]) -> bool:
+    """Validate certificates tuple."""
+    is_valid = (
+        all(isinstance(certificate, bytes) for certificate in certificates)
+        and len(certificates) == 3
+    )
+
+    if not is_valid:
+        log(ERROR, INVALID_CERTIFICATES_ERR_MSG)
+
+    return is_valid
+
+
+def generic_create_grpc_server(  # pylint: disable=too-many-arguments,R0917
+    servicer_and_add_fn: tuple[Any, AddServicerToServerFn],
+    server_address: str,
+    max_concurrent_workers: int = 1000,
+    max_message_length: int = GRPC_MAX_MESSAGE_LENGTH,
+    keepalive_time_ms: int = 210000,
+    certificates: Optional[tuple[bytes, bytes, bytes]] = None,
+    interceptors: Optional[Sequence[grpc.ServerInterceptor]] = None,
+) -> grpc.Server:
+    """Create a gRPC server with a single servicer.
+
+    Parameters
+    ----------
+    servicer_and_add_fn : tuple
+        A tuple holding a servicer implementation and a matching
+        add_Servicer_to_server function.
+    server_address : str
+        Server address in the form of HOST:PORT e.g. "[::]:8080"
+    max_concurrent_workers : int
+        Maximum number of clients the server can process before returning
+        RESOURCE_EXHAUSTED status (default: 1000)
+    max_message_length : int
+        Maximum message length that the server can send or receive.
+        Int valued in bytes. -1 means unlimited. (default: GRPC_MAX_MESSAGE_LENGTH)
+    keepalive_time_ms : int
+        Flower uses a default gRPC keepalive time of 210000ms (3 minutes 30 seconds)
+        because some cloud providers (for example, Azure) agressively clean up idle
+        TCP connections by terminating them after some time (4 minutes in the case
+        of Azure). Flower does not use application-level keepalive signals and relies
+        on the assumption that the transport layer will fail in cases where the
+        connection is no longer active. `keepalive_time_ms` can be used to customize
+        the keepalive interval for specific environments. The default Flower gRPC
+        keepalive of 210000 ms (3 minutes 30 seconds) ensures that Flower can keep
+        the long running streaming connection alive in most environments. The actual
+        gRPC default of this setting is 7200000 (2 hours), which results in dropped
+        connections in some cloud environments.
+
+        These settings are related to the issue described here:
+        - https://github.com/grpc/proposal/blob/master/A8-client-side-keepalive.md
+        - https://github.com/grpc/grpc/blob/master/doc/keepalive.md
+        - https://grpc.io/docs/guides/performance/
+
+        Mobile Flower clients may choose to increase this value if their server
+        environment allows long-running idle TCP connections.
+        (default: 210000)
+    certificates : Tuple[bytes, bytes, bytes] (default: None)
+        Tuple containing root certificate, server certificate, and private key to
+        start a secure SSL-enabled server. The tuple is expected to have three bytes
+        elements in the following order:
+
+            * CA certificate.
+            * server certificate.
+            * server private key.
+    interceptors : Optional[Sequence[grpc.ServerInterceptor]] (default: None)
+        A list of gRPC interceptors.
+
+    Returns
+    -------
+    server : grpc.Server
+        A non-running instance of a gRPC server.
+    """
+    # Check if port is in use
+    if is_port_in_use(server_address):
+        sys.exit(f"Port in server address {server_address} is already in use.")
+
+    # Deconstruct tuple into servicer and function
+    servicer, add_servicer_to_server_fn = servicer_and_add_fn
+
+    # Possible options:
+    # https://github.com/grpc/grpc/blob/v1.43.x/include/grpc/impl/codegen/grpc_types.h
+    options = [
+        # Maximum number of concurrent incoming streams to allow on a http2
+        # connection. Int valued.
+        ("grpc.max_concurrent_streams", max(100, max_concurrent_workers)),
+        # Maximum message length that the channel can send.
+        # Int valued, bytes. -1 means unlimited.
+        ("grpc.max_send_message_length", max_message_length),
+        # Maximum message length that the channel can receive.
+        # Int valued, bytes. -1 means unlimited.
+        ("grpc.max_receive_message_length", max_message_length),
+        # The gRPC default for this setting is 7200000 (2 hours). Flower uses a
+        # customized default of 210000 (3 minutes and 30 seconds) to improve
+        # compatibility with popular cloud providers. Mobile Flower clients may
+        # choose to increase this value if their server environment allows
+        # long-running idle TCP connections.
+        ("grpc.keepalive_time_ms", keepalive_time_ms),
+        # Setting this to zero will allow sending unlimited keepalive pings in between
+        # sending actual data frames.
+        ("grpc.http2.max_pings_without_data", 0),
+        # Is it permissible to send keepalive pings from the client without
+        # any outstanding streams. More explanation here:
+        # https://github.com/adap/flower/pull/2197
+        ("grpc.keepalive_permit_without_calls", 0),
+    ]
+
+    server = grpc.server(
+        concurrent.futures.ThreadPoolExecutor(max_workers=max_concurrent_workers),
+        # Set the maximum number of concurrent RPCs this server will service before
+        # returning RESOURCE_EXHAUSTED status, or None to indicate no limit.
+        maximum_concurrent_rpcs=max_concurrent_workers,
+        options=options,
+        interceptors=interceptors,
+    )
+    add_servicer_to_server_fn(servicer, server)
+
+    if certificates is not None:
+        if not valid_certificates(certificates):
+            sys.exit(1)
+
+        root_certificate_b, certificate_b, private_key_b = certificates
+
+        server_credentials = grpc.ssl_server_credentials(
+            ((private_key_b, certificate_b),),
+            root_certificates=root_certificate_b,
+            # A boolean indicating whether or not to require clients to be
+            # authenticated. May only be True if root_certificates is not None.
+            # We are explicitly setting the current gRPC default to document
+            # the option. For further reference see:
+            # https://grpc.github.io/grpc/python/grpc.html#create-server-credentials
+            require_client_auth=False,
+        )
+        server.add_secure_port(server_address, server_credentials)
+    else:
+        server.add_insecure_port(server_address)
+
+    return server

flwr/common/logger.py

@@ -15,10 +15,28 @@
 """Flower Logger."""
 
 
+import json as _json
 import logging
+import re
+import sys
+import threading
+import time
+from io import StringIO
 from logging import WARN, LogRecord
 from logging.handlers import HTTPHandler
-from typing import TYPE_CHECKING, Any, Dict, Optional, TextIO, Tuple
+from queue import Empty, Queue
+from typing import TYPE_CHECKING, Any, Optional, TextIO, Union
+
+import grpc
+import typer
+from rich.console import Console
+
+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"
@@ -82,13 +100,20 @@ class ConsoleHandler(StreamHandler):
         return formatter.format(record)
 
 
-def update_console_handler(level: int, timestamps: bool, colored: bool) -> None:
+def update_console_handler(
+    level: Optional[int] = None,
+    timestamps: Optional[bool] = None,
+    colored: Optional[bool] = None,
+) -> None:
     """Update the logging handler."""
     for handler in logging.getLogger(LOGGER_NAME).handlers:
         if isinstance(handler, ConsoleHandler):
-            handler.setLevel(level)
-            handler.timestamps = timestamps
-            handler.colored = colored
+            if level is not None:
+                handler.setLevel(level)
+            if timestamps is not None:
+                handler.timestamps = timestamps
+            if colored is not None:
+                handler.colored = colored
 
 
 # Configure console logger
@@ -104,7 +129,7 @@ FLOWER_LOGGER.addHandler(console_handler)
 class CustomHTTPHandler(HTTPHandler):
     """Custom HTTPHandler which overrides the mapLogRecords method."""
 
-    # pylint: disable=too-many-arguments,bad-option-value,R1725
+    # pylint: disable=too-many-arguments,bad-option-value,R1725,R0917
     def __init__(
         self,
         identifier: str,
@@ -112,12 +137,12 @@ class CustomHTTPHandler(HTTPHandler):
         url: str,
         method: str = "GET",
         secure: bool = False,
-        credentials: Optional[Tuple[str, str]] = None,
+        credentials: Optional[tuple[str, str]] = None,
     ) -> None:
         super().__init__(host, url, method, secure, credentials)
         self.identifier = identifier
 
-    def mapLogRecord(self, record: LogRecord) -> Dict[str, Any]:
+    def mapLogRecord(self, record: LogRecord) -> dict[str, Any]:
         """Filter for the properties to be send to the logserver."""
         record_dict = record.__dict__
         return {
@@ -164,13 +189,13 @@ logger = logging.getLogger(LOGGER_NAME)  # pylint: disable=invalid-name
 log = logger.log  # pylint: disable=invalid-name
 
 
-def warn_experimental_feature(name: str) -> None:
-    """Warn the user when they use an experimental feature."""
+def warn_preview_feature(name: str) -> None:
+    """Warn the user when they use a preview feature."""
     log(
         WARN,
-        """EXPERIMENTAL FEATURE: %s
+        """PREVIEW FEATURE: %s
 
-            This is an experimental feature. It could change significantly or be removed
+            This is a preview feature. It could change significantly or be removed
             entirely in future versions of Flower.
         """,
         name,
@@ -188,3 +213,196 @@ def warn_deprecated_feature(name: str) -> None:
         """,
         name,
     )
+
+
+def warn_deprecated_feature_with_example(
+    deprecation_message: str, example_message: str, code_example: str
+) -> None:
+    """Warn if a feature is deprecated and show code example."""
+    log(
+        WARN,
+        """DEPRECATED FEATURE: %s
+
+            Check the following `FEATURE UPDATE` warning message for the preferred
+            new mechanism to use this feature in Flower.
+        """,
+        deprecation_message,
+    )
+    log(
+        WARN,
+        """FEATURE UPDATE: %s
+        ------------------------------------------------------------
+        %s
+        ------------------------------------------------------------
+        """,
+        example_message,
+        code_example,
+    )
+
+
+def warn_unsupported_feature(name: str) -> None:
+    """Warn the user when they use an unsupported feature."""
+    log(
+        WARN,
+        """UNSUPPORTED FEATURE: %s
+
+            This is an unsupported feature. It will be removed
+            entirely in future versions of Flower.
+        """,
+        name,
+    )
+
+
+def set_logger_propagation(
+    child_logger: logging.Logger, value: bool = True
+) -> logging.Logger:
+    """Set the logger propagation attribute.
+
+    Parameters
+    ----------
+    child_logger : logging.Logger
+        Child logger object
+    value : bool
+        Boolean setting for propagation. If True, both parent and child logger
+        display messages. Otherwise, only the child logger displays a message.
+        This False setting prevents duplicate logs in Colab notebooks.
+        Reference: https://stackoverflow.com/a/19561320
+
+    Returns
+    -------
+    logging.Logger
+        Child logger object with updated propagation setting
+    """
+    child_logger.propagate = value
+    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 redirect_output(output_buffer: StringIO) -> None:
+    """Redirect stdout and stderr to text I/O buffer."""
+    sys.stdout = output_buffer
+    sys.stderr = output_buffer
+    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)
+    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()
+
+
+def _remove_emojis(text: str) -> str:
+    """Remove emojis from the provided text."""
+    emoji_pattern = re.compile(
+        "["
+        "\U0001F600-\U0001F64F"  # Emoticons
+        "\U0001F300-\U0001F5FF"  # Symbols & Pictographs
+        "\U0001F680-\U0001F6FF"  # Transport & Map Symbols
+        "\U0001F1E0-\U0001F1FF"  # Flags
+        "\U00002702-\U000027B0"  # Dingbats
+        "\U000024C2-\U0001F251"
+        "]+",
+        flags=re.UNICODE,
+    )
+    return emoji_pattern.sub(r"", text)
+
+
+def print_json_error(msg: str, e: Union[typer.Exit, Exception]) -> None:
+    """Print error message as JSON."""
+    Console().print_json(
+        _json.dumps(
+            {
+                "success": False,
+                "error-message": _remove_emojis(str(msg) + "\n" + str(e)),
+            }
+        )
+    )