flwr 1.15.2__py3-none-any.whl → 1.17.0__py3-none-any.whl

flwr/common/address.py

@@ -15,10 +15,13 @@
 """Flower IP address utils."""
 
 
+import re
 import socket
 from ipaddress import ip_address
 from typing import Optional
 
+import grpc
+
 IPV6: int = 6
 
 
@@ -101,3 +104,35 @@ def is_port_in_use(address: str) -> bool:
             return True
 
         return False
+
+
+def get_ip_address_from_servicer_context(context: grpc.ServicerContext) -> str:
+    """Extract the client's IPv4 or IPv6 address from the gRPC ServicerContext.
+
+    Parameters
+    ----------
+    context : grpc.ServicerContext
+        The gRPC ServicerContext object. The context.peer() returns a string like
+        "ipv4:127.0.0.1:56789" for IPv4 and "ipv6:[2001:db8::1]:54321" for IPv6.
+
+    Returns
+    -------
+    str
+        If one of the format matches, the function will return the client's IP address,
+        otherwise, it will raise a ValueError.
+    """
+    peer: str = context.peer()
+    # Match IPv4: "ipv4:IP:port"
+    ipv4_match = re.match(r"^ipv4:(?P<ip>[^:]+):", peer)
+    if ipv4_match:
+        return ipv4_match.group("ip")
+
+    # Match IPv6: "ipv6:[IP]:port"
+    ipv6_match = re.match(r"^ipv6:\[(?P<ip>[^\]]+)\]:", peer)
+    if ipv6_match:
+        return ipv6_match.group("ip")
+
+    raise ValueError(
+        f"Unsupported peer address format: {peer} for the transport protocol. "
+        "The supported formats are ipv4:IP:port and ipv6:[IP]:port."
+    )

flwr/common/args.py

@@ -43,7 +43,8 @@ def add_args_flwr_app_common(parser: argparse.ArgumentParser) -> None:
         "--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. "
+        "paths are provided. Data transmitted between the gRPC client and server "
+        "is not encrypted. By default, the server runs with HTTPS enabled. "
         "Use this flag only if you understand the risks.",
     )
 
@@ -99,7 +100,12 @@ def try_obtain_server_certificates(
 ) -> Optional[tuple[bytes, bytes, bytes]]:
     """Validate and return the CA cert, server cert, and server private key."""
     if args.insecure:
-        log(WARN, "Option `--insecure` was set. Starting insecure HTTP server.")
+        log(
+            WARN,
+            "Option `--insecure` was set. Starting insecure HTTP server with "
+            "unencrypted communication (TLS disabled). Proceed only if you understand "
+            "the risks.",
+        )
         return None
     # Check if certificates are provided
     if args.ssl_certfile and args.ssl_keyfile and args.ssl_ca_certfile:

flwr/common/auth_plugin/auth_plugin.py

@@ -20,6 +20,7 @@ from collections.abc import Sequence
 from pathlib import Path
 from typing import Optional, Union
 
+from flwr.common.typing import UserInfo
 from flwr.proto.exec_pb2_grpc import ExecStub
 
 from ..typing import UserAuthCredentials, UserAuthLoginDetails
@@ -49,7 +50,7 @@ class ExecAuthPlugin(ABC):
     @abstractmethod
     def validate_tokens_in_metadata(
         self, metadata: Sequence[tuple[str, Union[str, bytes]]]
-    ) -> bool:
+    ) -> tuple[bool, Optional[UserInfo]]:
         """Validate authentication tokens in the provided metadata."""
 
     @abstractmethod

flwr/common/config.py

@@ -34,7 +34,7 @@ from flwr.common.constant import (
 )
 from flwr.common.typing import Run, UserConfig, UserConfigValue
 
-from . import ConfigsRecord, object_ref
+from . import ConfigRecord, object_ref
 
 T_dict = TypeVar("T_dict", bound=dict[str, Any])  # pylint: disable=invalid-name
 
@@ -260,9 +260,9 @@ def get_metadata_from_config(config: dict[str, Any]) -> tuple[str, str]:
     )
 
 
-def user_config_to_configsrecord(config: UserConfig) -> ConfigsRecord:
-    """Construct a `ConfigsRecord` out of a `UserConfig`."""
-    c_record = ConfigsRecord()
+def user_config_to_configrecord(config: UserConfig) -> ConfigRecord:
+    """Construct a `ConfigRecord` out of a `UserConfig`."""
+    c_record = ConfigRecord()
     for k, v in config.items():
         c_record[k] = v
 

flwr/common/constant.py

@@ -61,6 +61,7 @@ PING_CALL_TIMEOUT = 5
 PING_BASE_MULTIPLIER = 0.8
 PING_RANDOM_RANGE = (-0.1, 0.1)
 PING_MAX_INTERVAL = 1e300
+PING_PATIENCE = 2
 
 # IDs
 RUN_ID_NUM_BYTES = 8
@@ -120,6 +121,9 @@ TIMESTAMP_HEADER = "flwr-timestamp"
 TIMESTAMP_TOLERANCE = 10  # General tolerance for timestamp verification
 SYSTEM_TIME_TOLERANCE = 5  # Allowance for system time drift
 
+# Constants for ArrayRecord
+GC_THRESHOLD = 200_000_000  # 200 MB
+
 
 class MessageType:
     """Message type."""
@@ -127,6 +131,7 @@ class MessageType:
     TRAIN = "train"
     EVALUATE = "evaluate"
     QUERY = "query"
+    SYSTEM = "system"
 
     def __new__(cls) -> MessageType:
         """Prevent instantiation."""
@@ -162,6 +167,7 @@ class ErrorCode:
     CLIENT_APP_RAISED_EXCEPTION = 2
     MESSAGE_UNAVAILABLE = 3
     REPLY_MESSAGE_UNAVAILABLE = 4
+    NODE_UNAVAILABLE = 5
 
     def __new__(cls) -> ErrorCode:
         """Prevent instantiation."""
@@ -212,3 +218,13 @@ class AuthType:
     def __new__(cls) -> AuthType:
         """Prevent instantiation."""
         raise TypeError(f"{cls.__name__} cannot be instantiated.")
+
+
+class EventLogWriterType:
+    """Event log writer types."""
+
+    STDOUT = "stdout"
+
+    def __new__(cls) -> EventLogWriterType:
+        """Prevent instantiation."""
+        raise TypeError(f"{cls.__name__} cannot be instantiated.")

flwr/common/context.py

@@ -17,7 +17,7 @@
 
 from dataclasses import dataclass
 
-from .record import RecordSet
+from .record import RecordDict
 from .typing import UserConfig
 
 
@@ -34,7 +34,7 @@ class Context:
     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
+    state : RecordDict
         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
@@ -50,7 +50,7 @@ class Context:
     run_id: int
     node_id: int
     node_config: UserConfig
-    state: RecordSet
+    state: RecordDict
     run_config: UserConfig
 
     def __init__(  # pylint: disable=too-many-arguments, too-many-positional-arguments
@@ -58,7 +58,7 @@ class Context:
         run_id: int,
         node_id: int,
         node_config: UserConfig,
-        state: RecordSet,
+        state: RecordDict,
         run_config: UserConfig,
     ) -> None:
         self.run_id = run_id

flwr/common/event_log_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.
+# ==============================================================================
+"""Event log plugin components."""
+
+
+from .event_log_plugin import EventLogWriterPlugin as EventLogWriterPlugin
+
+__all__ = [
+    "EventLogWriterPlugin",
+]

flwr/common/event_log_plugin/event_log_plugin.py

@@ -0,0 +1,60 @@
+# 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 Event Log Writer Plugin."""
+
+
+from abc import ABC, abstractmethod
+from typing import Optional, Union
+
+import grpc
+from google.protobuf.message import Message as GrpcMessage
+
+from flwr.common.typing import LogEntry, UserInfo
+
+
+class EventLogWriterPlugin(ABC):
+    """Abstract Flower Event Log Writer Plugin class for ExecServicer."""
+
+    @abstractmethod
+    def __init__(self) -> None:
+        """Abstract constructor."""
+
+    @abstractmethod
+    def compose_log_before_event(  # pylint: disable=too-many-arguments
+        self,
+        request: GrpcMessage,
+        context: grpc.ServicerContext,
+        user_info: Optional[UserInfo],
+        method_name: str,
+    ) -> LogEntry:
+        """Compose pre-event log entry from the provided request and context."""
+
+    @abstractmethod
+    def compose_log_after_event(  # pylint: disable=too-many-arguments,R0917
+        self,
+        request: GrpcMessage,
+        context: grpc.ServicerContext,
+        user_info: Optional[UserInfo],
+        method_name: str,
+        response: Optional[Union[GrpcMessage, BaseException]],
+    ) -> LogEntry:
+        """Compose post-event log entry from the provided response and context."""
+
+    @abstractmethod
+    def write_log(
+        self,
+        log_entry: LogEntry,
+    ) -> None:
+        """Write the event log to the specified data sink."""

flwr/common/grpc.py

@@ -27,7 +27,7 @@ import grpc
 from .address import is_port_in_use
 from .logger import log
 
-GRPC_MAX_MESSAGE_LENGTH: int = 536_870_912  # == 512 * 1024 * 1024
+GRPC_MAX_MESSAGE_LENGTH: int = 2_147_483_647  # == 2048 * 1024 * 1024 -1 (2GB)
 
 INVALID_CERTIFICATES_ERR_MSG = """
     When setting any of root_certificate, certificate, or private_key,

flwr/common/logger.py

@@ -250,9 +250,9 @@ def warn_deprecated_feature_with_example(
     log(
         WARN,
         """FEATURE UPDATE: %s
-        ------------------------------------------------------------
+            ------------------------------------------------------------
         %s
-        ------------------------------------------------------------
+            ------------------------------------------------------------
         """,
         example_message,
         code_example,