From aad87f983ff60834dba4a1f682a3f96d3dad1f0f Mon Sep 17 00:00:00 2001 From: bomanaps Date: Mon, 1 Sep 2025 11:58:42 +0100 Subject: [PATCH] Adress documentation comment --- docs/examples.multiple_connections.rst | 77 +++++++++++++++++++++++--- libp2p/network/swarm.py | 37 ++++++++++++- 2 files changed, 104 insertions(+), 10 deletions(-) diff --git a/docs/examples.multiple_connections.rst b/docs/examples.multiple_connections.rst index 814152b3..85ab8f2d 100644 --- a/docs/examples.multiple_connections.rst +++ b/docs/examples.multiple_connections.rst @@ -96,23 +96,46 @@ Production Configuration For production use, consider these settings: +**RetryConfig Parameters** + +The `RetryConfig` class controls connection retry behavior with exponential backoff: + +- **max_retries**: Maximum number of retry attempts before giving up (default: 3) +- **initial_delay**: Initial delay in seconds before the first retry (default: 0.1s) +- **max_delay**: Maximum delay cap to prevent excessive wait times (default: 30.0s) +- **backoff_multiplier**: Exponential backoff multiplier - each retry multiplies delay by this factor (default: 2.0) +- **jitter_factor**: Random jitter (0.0-1.0) to prevent synchronized retries (default: 0.1) + +**ConnectionConfig Parameters** + +The `ConnectionConfig` class manages multi-connection behavior: + +- **max_connections_per_peer**: Maximum connections allowed to a single peer (default: 3) +- **connection_timeout**: Timeout for establishing new connections in seconds (default: 30.0s) +- **load_balancing_strategy**: Strategy for distributing streams ("round_robin" or "least_loaded") + +**Load Balancing Strategies Explained** + +- **round_robin**: Cycles through connections in order, distributing load evenly. Simple and predictable. +- **least_loaded**: Selects the connection with the fewest active streams. Better for performance but more complex. + .. code-block:: python from libp2p.network.swarm import ConnectionConfig, RetryConfig # Production-ready configuration retry_config = RetryConfig( - max_retries=3, - initial_delay=0.1, - max_delay=30.0, - backoff_multiplier=2.0, - jitter_factor=0.1 + max_retries=3, # Maximum retry attempts before giving up + initial_delay=0.1, # Start with 100ms delay + max_delay=30.0, # Cap exponential backoff at 30 seconds + backoff_multiplier=2.0, # Double delay each retry (100ms -> 200ms -> 400ms) + jitter_factor=0.1 # Add 10% random jitter to prevent thundering herd ) connection_config = ConnectionConfig( - max_connections_per_peer=3, # Balance performance and resources - connection_timeout=30.0, # Reasonable timeout - load_balancing_strategy="round_robin" # Predictable behavior + max_connections_per_peer=3, # Allow up to 3 connections per peer + connection_timeout=30.0, # 30 second timeout for new connections + load_balancing_strategy="round_robin" # Simple, predictable load distribution ) swarm = new_swarm( @@ -120,6 +143,44 @@ For production use, consider these settings: connection_config=connection_config ) +**How RetryConfig Works in Practice** + +With the configuration above, connection retries follow this pattern: + +1. **Attempt 1**: Immediate connection attempt +2. **Attempt 2**: Wait 100ms ± 10ms jitter, then retry +3. **Attempt 3**: Wait 200ms ± 20ms jitter, then retry +4. **Attempt 4**: Wait 400ms ± 40ms jitter, then retry +5. **Attempt 5**: Wait 800ms ± 80ms jitter, then retry +6. **Attempt 6**: Wait 1.6s ± 160ms jitter, then retry +7. **Attempt 7**: Wait 3.2s ± 320ms jitter, then retry +8. **Attempt 8**: Wait 6.4s ± 640ms jitter, then retry +9. **Attempt 9**: Wait 12.8s ± 1.28s jitter, then retry +10. **Attempt 10**: Wait 25.6s ± 2.56s jitter, then retry +11. **Attempt 11**: Wait 30.0s (capped) ± 3.0s jitter, then retry +12. **Attempt 12**: Wait 30.0s (capped) ± 3.0s jitter, then retry +13. **Give up**: After 12 retries (3 initial + 9 retries), connection fails + +The jitter prevents multiple clients from retrying simultaneously, reducing server load. + +**Parameter Tuning Guidelines** + +**For Development/Testing:** +- Use lower `max_retries` (1-2) and shorter delays for faster feedback +- Example: `RetryConfig(max_retries=2, initial_delay=0.01, max_delay=0.1)` + +**For Production:** +- Use moderate `max_retries` (3-5) with reasonable delays for reliability +- Example: `RetryConfig(max_retries=5, initial_delay=0.1, max_delay=60.0)` + +**For High-Latency Networks:** +- Use higher `max_retries` (5-10) with longer delays +- Example: `RetryConfig(max_retries=8, initial_delay=0.5, max_delay=120.0)` + +**For Load Balancing:** +- Use `round_robin` for simple, predictable behavior +- Use `least_loaded` when you need optimal performance and can handle complexity + Architecture ------------ diff --git a/libp2p/network/swarm.py b/libp2p/network/swarm.py index 23a94fdb..5a3ce7bb 100644 --- a/libp2p/network/swarm.py +++ b/libp2p/network/swarm.py @@ -63,7 +63,26 @@ logger = logging.getLogger("libp2p.network.swarm") @dataclass class RetryConfig: - """Configuration for retry logic with exponential backoff.""" + """ + Configuration for retry logic with exponential backoff. + + This configuration controls how connection attempts are retried when they fail. + The retry mechanism uses exponential backoff with jitter to prevent thundering + herd problems in distributed systems. + + Attributes: + max_retries: Maximum number of retry attempts before giving up. + Default: 3 attempts + initial_delay: Initial delay in seconds before the first retry. + Default: 0.1 seconds (100ms) + max_delay: Maximum delay cap in seconds to prevent excessive wait times. + Default: 30.0 seconds + backoff_multiplier: Multiplier for exponential backoff (each retry multiplies + the delay by this factor). Default: 2.0 (doubles each time) + jitter_factor: Random jitter factor (0.0-1.0) to add randomness to delays + and prevent synchronized retries. Default: 0.1 (10% jitter) + + """ max_retries: int = 3 initial_delay: float = 0.1 @@ -74,7 +93,21 @@ class RetryConfig: @dataclass class ConnectionConfig: - """Configuration for multi-connection support.""" + """ + Configuration for multi-connection support. + + This configuration controls how multiple connections per peer are managed, + including connection limits, timeouts, and load balancing strategies. + + Attributes: + max_connections_per_peer: Maximum number of connections allowed to a single + peer. Default: 3 connections + connection_timeout: Timeout in seconds for establishing new connections. + Default: 30.0 seconds + load_balancing_strategy: Strategy for distributing streams across connections. + Options: "round_robin" (default) or "least_loaded" + + """ max_connections_per_peer: int = 3 connection_timeout: float = 30.0