flwr-nightly 1.15.0.dev20250104__py3-none-any.whl → 1.15.0.dev20250123__py3-none-any.whl

flwr/common/exit/exit.py

@@ -0,0 +1,99 @@
+# 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.
+# ==============================================================================
+"""Unified exit function."""
+
+
+from __future__ import annotations
+
+import sys
+from logging import ERROR, INFO
+from typing import Any, NoReturn
+
+from flwr.common import EventType, event
+
+from ..logger import log
+from .exit_code import EXIT_CODE_HELP
+
+HELP_PAGE_URL = "https://flower.ai/docs/framework/ref-exit-codes/"
+
+
+def flwr_exit(
+    code: int,
+    message: str | None = None,
+    event_type: EventType | None = None,
+    event_details: dict[str, Any] | None = None,
+) -> NoReturn:
+    """Handle application exit with an optional message.
+
+    The exit message logged and displayed will follow this structure:
+
+    >>> Exit Code: <code>
+    >>> <message>
+    >>> <short-help-message>
+    >>>
+    >>> For more information, visit: <help-page-url>
+
+    - `<code>`: The unique exit code representing the termination reason.
+    - `<message>`: Optional context or additional information about the exit.
+    - `<short-help-message>`: A brief explanation for the given exit code.
+    - `<help-page-url>`: A URL providing detailed documentation and resolution steps.
+    """
+    is_error = not 0 <= code < 100  # 0-99 are success exit codes
+
+    # Construct exit message
+    exit_message = f"Exit Code: {code}\n" if is_error else ""
+    exit_message += message or ""
+    if short_help_message := EXIT_CODE_HELP.get(code, ""):
+        exit_message += f"\n{short_help_message}"
+
+    # Set log level and system exit code
+    log_level = ERROR if is_error else INFO
+    sys_exit_code = 1 if is_error else 0
+
+    # Add help URL for non-successful/graceful exits
+    if is_error:
+        help_url = f"{HELP_PAGE_URL}{code}.html"
+        exit_message += f"\n\nFor more information, visit: <{help_url}>"
+
+    # Telemetry event
+    event_type = event_type or _try_obtain_telemetry_event()
+    if event_type:
+        event_details = event_details or {}
+        event_details["exit_code"] = code
+        event(event_type, event_details).result()
+
+    # Log the exit message
+    log(log_level, exit_message)
+
+    # Exit
+    sys.exit(sys_exit_code)
+
+
+# pylint: disable-next=too-many-return-statements
+def _try_obtain_telemetry_event() -> EventType | None:
+    """Try to obtain a telemetry event."""
+    if sys.argv[0].endswith("flower-superlink"):
+        return EventType.RUN_SUPERLINK_LEAVE
+    if sys.argv[0].endswith("flower-supernode"):
+        return EventType.RUN_SUPERNODE_LEAVE
+    if sys.argv[0].endswith("flwr-serverapp"):
+        return EventType.FLWR_SERVERAPP_RUN_LEAVE
+    if sys.argv[0].endswith("flwr-clientapp"):
+        return None  # Not yet implemented
+    if sys.argv[0].endswith("flwr-simulation"):
+        return EventType.FLWR_SIMULATION_RUN_LEAVE
+    if sys.argv[0].endswith("flower-simulation"):
+        return EventType.CLI_FLOWER_SIMULATION_LEAVE
+    return None

flwr/common/exit/exit_code.py

@@ -0,0 +1,93 @@
+# 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.
+# ==============================================================================
+"""Exit codes."""
+
+
+from __future__ import annotations
+
+
+class ExitCode:
+    """Exit codes for Flower components."""
+
+    # Success exit codes (0-99)
+    SUCCESS = 0  # Successful exit without any errors or signals
+    GRACEFUL_EXIT_SIGINT = 1  # Graceful exit triggered by SIGINT
+    GRACEFUL_EXIT_SIGQUIT = 2  # Graceful exit triggered by SIGQUIT
+    GRACEFUL_EXIT_SIGTERM = 3  # Graceful exit triggered by SIGTERM
+
+    # SuperLink-specific exit codes (100-199)
+    SUPERLINK_THREAD_CRASH = 100
+
+    # ServerApp-specific exit codes (200-299)
+
+    # SuperNode-specific exit codes (300-399)
+    SUPERNODE_REST_ADDRESS_INVALID = 300
+    SUPERNODE_NODE_AUTH_KEYS_REQUIRED = 301
+    SUPERNODE_NODE_AUTH_KEYS_INVALID = 302
+
+    # ClientApp-specific exit codes (400-499)
+
+    # Simulation-specific exit codes (500-599)
+
+    # Common exit codes (600-)
+    COMMON_ADDRESS_INVALID = 600
+    COMMON_MISSING_EXTRA_REST = 601
+    COMMON_TLS_NOT_SUPPORTED = 602
+
+    def __new__(cls) -> ExitCode:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+# All short help messages for exit codes
+EXIT_CODE_HELP = {
+    # Success exit codes (0-99)
+    ExitCode.SUCCESS: "",
+    ExitCode.GRACEFUL_EXIT_SIGINT: "",
+    ExitCode.GRACEFUL_EXIT_SIGQUIT: "",
+    ExitCode.GRACEFUL_EXIT_SIGTERM: "",
+    # SuperLink-specific exit codes (100-199)
+    ExitCode.SUPERLINK_THREAD_CRASH: "An important background thread has crashed.",
+    # ServerApp-specific exit codes (200-299)
+    # SuperNode-specific exit codes (300-399)
+    ExitCode.SUPERNODE_REST_ADDRESS_INVALID: (
+        "When using the REST API, please provide `https://` or "
+        "`http://` before the server address (e.g. `http://127.0.0.1:8080`)"
+    ),
+    ExitCode.SUPERNODE_NODE_AUTH_KEYS_REQUIRED: (
+        "Node authentication requires file paths to both "
+        "'--auth-supernode-private-key' and '--auth-supernode-public-key' "
+        "to be provided (providing only one of them is not sufficient)."
+    ),
+    ExitCode.SUPERNODE_NODE_AUTH_KEYS_INVALID: (
+        "Node uthentication requires elliptic curve private and public key pair. "
+        "Please ensure that the file path points to a valid private/public key "
+        "file and try again."
+    ),
+    # ClientApp-specific exit codes (400-499)
+    # Simulation-specific exit codes (500-599)
+    # Common exit codes (600-)
+    ExitCode.COMMON_ADDRESS_INVALID: (
+        "Please provide a valid URL, IPv4 or IPv6 address."
+    ),
+    ExitCode.COMMON_MISSING_EXTRA_REST: """
+Extra dependencies required for using the REST-based Fleet API are missing.
+
+To use the REST API, install `flwr` with the `rest` extra:
+
+    `pip install "flwr[rest]"`.
+""",
+    ExitCode.COMMON_TLS_NOT_SUPPORTED: "Please use the '--insecure' flag.",
+}

flwr/common/exit_handlers.py

@@ -15,28 +15,38 @@
 """Common function to register exit handlers for server and client."""
 
 
-import sys
-from signal import SIGINT, SIGTERM, signal
+from signal import SIGINT, SIGQUIT, SIGTERM, signal
 from threading import Thread
 from types import FrameType
 from typing import Optional
 
 from grpc import Server
 
-from flwr.common.telemetry import EventType, event
+from flwr.common.telemetry import EventType
+
+from .exit import ExitCode, flwr_exit
+
+SIGNAL_TO_EXIT_CODE = {
+    SIGINT: ExitCode.GRACEFUL_EXIT_SIGINT,
+    SIGQUIT: ExitCode.GRACEFUL_EXIT_SIGQUIT,
+    SIGTERM: ExitCode.GRACEFUL_EXIT_SIGTERM,
+}
 
 
 def register_exit_handlers(
     event_type: EventType,
+    exit_message: Optional[str] = None,
     grpc_servers: Optional[list[Server]] = None,
     bckg_threads: Optional[list[Thread]] = None,
 ) -> None:
-    """Register exit handlers for `SIGINT` and `SIGTERM` signals.
+    """Register exit handlers for `SIGINT`, `SIGTERM` and `SIGQUIT` signals.
 
     Parameters
     ----------
     event_type : EventType
         The telemetry event that should be logged before exit.
+    exit_message : Optional[str] (default: None)
+        The message to be logged before exiting.
     grpc_servers: Optional[List[Server]] (default: None)
         An otpional list of gRPC servers that need to be gracefully
         terminated before exiting.
@@ -46,6 +56,7 @@ def register_exit_handlers(
     """
     default_handlers = {
         SIGINT: None,
+        SIGQUIT: None,
         SIGTERM: None,
     }
 
@@ -61,8 +72,6 @@ def register_exit_handlers(
         # Reset to default handler
         signal(signalnum, default_handlers[signalnum])
 
-        event_res = event(event_type=event_type)
-
         if grpc_servers is not None:
             for grpc_server in grpc_servers:
                 grpc_server.stop(grace=1)
@@ -71,16 +80,21 @@ def register_exit_handlers(
             for bckg_thread in bckg_threads:
                 bckg_thread.join()
 
-        # Ensure event has happend
-        event_res.result()
-
         # Setup things for graceful exit
-        sys.exit(0)
+        flwr_exit(
+            code=SIGNAL_TO_EXIT_CODE[signalnum],
+            message=exit_message,
+            event_type=event_type,
+        )
 
     default_handlers[SIGINT] = signal(  # type: ignore
         SIGINT,
         graceful_exit_handler,  # type: ignore
     )
+    default_handlers[SIGQUIT] = signal(  # type: ignore
+        SIGQUIT,
+        graceful_exit_handler,  # type: ignore
+    )
     default_handlers[SIGTERM] = signal(  # type: ignore
         SIGTERM,
         graceful_exit_handler,  # type: ignore

flwr/common/grpc.py

@@ -15,16 +15,33 @@
 """Utility functions for gRPC."""
 
 
+import concurrent.futures
+import os
+import sys
 from collections.abc import Sequence
-from logging import DEBUG
-from typing import Optional
+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]
+
+if "GRPC_VERBOSITY" not in os.environ:
+    os.environ["GRPC_VERBOSITY"] = "error"
+# The following flags can be uncommented for debugging. Other possible values:
+# https://github.com/grpc/grpc/blob/master/doc/environment_variables.md
+# os.environ["GRPC_TRACE"] = "tcp,http"
+
 
 def create_channel(
     server_address: str,
@@ -66,3 +83,144 @@ def create_channel(
         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

@@ -320,7 +320,7 @@ def _log_uploader(
 ) -> None:
     """Upload logs to the SuperLink."""
     exit_flag = False
-    node = Node(node_id=node_id, anonymous=False)
+    node = Node(node_id=node_id)
     msgs: list[str] = []
     while True:
         # Fetch all messages from the queue

flwr/common/secure_aggregation/crypto/symmetric_encryption.py

@@ -117,3 +117,48 @@ def verify_hmac(key: bytes, message: bytes, hmac_value: bytes) -> bool:
         return True
     except InvalidSignature:
         return False
+
+
+def sign_message(private_key: ec.EllipticCurvePrivateKey, message: bytes) -> bytes:
+    """Sign a message using the provided EC private key.
+
+    Parameters
+    ----------
+    private_key : ec.EllipticCurvePrivateKey
+        The EC private key to sign the message with.
+    message : bytes
+        The message to be signed.
+
+    Returns
+    -------
+    bytes
+        The signature of the message.
+    """
+    signature = private_key.sign(message, ec.ECDSA(hashes.SHA256()))
+    return signature
+
+
+def verify_signature(
+    public_key: ec.EllipticCurvePublicKey, message: bytes, signature: bytes
+) -> bool:
+    """Verify a signature against a message using the provided EC public key.
+
+    Parameters
+    ----------
+    public_key : ec.EllipticCurvePublicKey
+        The EC public key to verify the signature.
+    message : bytes
+        The original message.
+    signature : bytes
+        The signature to verify.
+
+    Returns
+    -------
+    bool
+        True if the signature is valid, False otherwise.
+    """
+    try:
+        public_key.verify(signature, message, ec.ECDSA(hashes.SHA256()))
+        return True
+    except InvalidSignature:
+        return False

flwr/common/serde.py

@@ -21,6 +21,8 @@ from typing import Any, TypeVar, cast
 
 from google.protobuf.message import Message as GrpcMessage
 
+from flwr.common.constant import SUPERLINK_NODE_ID
+
 # pylint: disable=E0611
 from flwr.proto.clientappio_pb2 import ClientAppOutputCode, ClientAppOutputStatus
 from flwr.proto.error_pb2 import Error as ProtoError
@@ -605,8 +607,8 @@ def message_to_taskins(message: Message) -> TaskIns:
         group_id=md.group_id,
         run_id=md.run_id,
         task=Task(
-            producer=Node(node_id=0, anonymous=True),  # Assume driver node
-            consumer=Node(node_id=md.dst_node_id, anonymous=False),
+            producer=Node(node_id=SUPERLINK_NODE_ID),  # Assume driver node
+            consumer=Node(node_id=md.dst_node_id),
             created_at=md.created_at,
             ttl=md.ttl,
             ancestry=[md.reply_to_message] if md.reply_to_message != "" else [],
@@ -659,8 +661,8 @@ def message_to_taskres(message: Message) -> TaskRes:
         group_id=md.group_id,
         run_id=md.run_id,
         task=Task(
-            producer=Node(node_id=md.src_node_id, anonymous=False),
-            consumer=Node(node_id=0, anonymous=True),  # Assume driver node
+            producer=Node(node_id=md.src_node_id),
+            consumer=Node(node_id=SUPERLINK_NODE_ID),  # Assume driver node
             created_at=md.created_at,
             ttl=md.ttl,
             ancestry=[md.reply_to_message] if md.reply_to_message != "" else [],

flwr/common/typing.py

@@ -266,3 +266,23 @@ class InvalidRunStatusException(BaseException):
     def __init__(self, message: str) -> None:
         super().__init__(message)
         self.message = message
+
+
+# OIDC user authentication types
+@dataclass
+class UserAuthLoginDetails:
+    """User authentication login details."""
+
+    auth_type: str
+    device_code: str
+    verification_uri_complete: str
+    expires_in: int
+    interval: int
+
+
+@dataclass
+class UserAuthCredentials:
+    """User authentication tokens."""
+
+    access_token: str
+    refresh_token: str

flwr/proto/clientappio_pb2.py

@@ -1,12 +1,22 @@
 # -*- coding: utf-8 -*-
 # Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
 # source: flwr/proto/clientappio.proto
-# Protobuf Python Version: 4.25.0
+# Protobuf Python Version: 5.29.0
 """Generated protocol buffer code."""
 from google.protobuf import descriptor as _descriptor
 from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
 from google.protobuf import symbol_database as _symbol_database
 from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    5,
+    29,
+    0,
+    '',
+    'flwr/proto/clientappio.proto'
+)
 # @@protoc_insertion_point(imports)
 
 _sym_db = _symbol_database.Default()
@@ -22,8 +32,8 @@ DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x1c\x66lwr/proto/
 _globals = globals()
 _builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
 _builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'flwr.proto.clientappio_pb2', _globals)
-if _descriptor._USE_C_DESCRIPTORS == False:
-  DESCRIPTOR._options = None
+if not _descriptor._USE_C_DESCRIPTORS:
+  DESCRIPTOR._loaded_options = None
   _globals['_CLIENTAPPOUTPUTCODE']._serialized_start=675
   _globals['_CLIENTAPPOUTPUTCODE']._serialized_end=751
   _globals['_CLIENTAPPOUTPUTSTATUS']._serialized_start=114