Add a generator of backoff delays.

Author: aaugustin

docs/reference/variables.rst

@@ -13,7 +13,7 @@ Logging
 See the :doc:`logging guide <../topics/logging>` for details.
 
 Security
-........
+--------
 
 .. envvar:: WEBSOCKETS_SERVER
 
@@ -31,18 +31,49 @@ Security
 
     Maximum length of the request or status line in the opening handshake.
 
-    The default value is ``8192``.
+    The default value is ``8192`` bytes.
 
 .. envvar:: WEBSOCKETS_MAX_NUM_HEADERS
 
     Maximum number of HTTP headers in the opening handshake.
 
-    The default value is ``128``.
+    The default value is ``128`` bytes.
 
 .. envvar:: WEBSOCKETS_MAX_BODY_SIZE
 
     Maximum size of the body of an HTTP response in the opening handshake.
 
-    The default value is ``1_048_576`` (1 MiB).
+    The default value is ``1_048_576`` bytes (1 MiB).
 
 See the :doc:`security guide <../topics/security>` for details.
+
+Reconnection
+------------
+
+Reconnection attempts are spaced out with truncated exponential backoff.
+
+.. envvar:: BACKOFF_INITIAL_DELAY
+
+    The first attempt is delayed by a random amount of time between ``0`` and
+    ``BACKOFF_INITIAL_DELAY`` seconds.
+
+    The default value is ``5.0`` seconds.
+
+.. envvar:: BACKOFF_MIN_DELAY
+
+    The second attempt is delayed by ``BACKOFF_MIN_DELAY`` seconds.
+
+    The default value is ``3.1`` seconds.
+
+.. envvar:: BACKOFF_FACTOR
+
+    After the second attempt, the delay is multiplied by ``BACKOFF_FACTOR``
+    between each attempt.
+
+    The default value is ``1.618``.
+
+.. envvar:: BACKOFF_MAX_DELAY
+
+    The delay between attempts is capped at ``BACKOFF_MAX_DELAY`` seconds.
+
+    The default value is ``90.0`` seconds.

src/websockets/client.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import os
+import random
 import warnings
 from typing import Any, Generator, Sequence
 
@@ -357,3 +359,33 @@ def __init__(self, *args: Any, **kwargs: Any) -> None:
             DeprecationWarning,
         )
         super().__init__(*args, **kwargs)
+
+
+BACKOFF_INITIAL_DELAY = float(os.environ.get("WEBSOCKETS_BACKOFF_INITIAL_DELAY", "5"))
+BACKOFF_MIN_DELAY = float(os.environ.get("WEBSOCKETS_BACKOFF_MIN_DELAY", "3.1"))
+BACKOFF_MAX_DELAY = float(os.environ.get("WEBSOCKETS_BACKOFF_MAX_DELAY", "90.0"))
+BACKOFF_FACTOR = float(os.environ.get("WEBSOCKETS_BACKOFF_FACTOR", "1.618"))
+
+
+def backoff(
+    initial_delay: float = BACKOFF_INITIAL_DELAY,
+    min_delay: float = BACKOFF_MIN_DELAY,
+    max_delay: float = BACKOFF_MAX_DELAY,
+    factor: float = BACKOFF_FACTOR,
+) -> Generator[float, None, None]:
+    """
+    Generate a series of backoff delays between reconnection attempts.
+
+    Yields:
+        How many seconds to wait before retrying to connect.
+
+    """
+    # Add a random initial delay between 0 and 5 seconds.
+    # See 7.2.3. Recovering from Abnormal Closure in RFC 6455.
+    yield random.random() * initial_delay
+    delay = min_delay
+    while delay < max_delay:
+        yield delay
+        delay *= factor
+    while True:
+        yield max_delay

src/websockets/legacy/client.py

@@ -3,6 +3,7 @@
 import asyncio
 import functools
 import logging
+import os
 import random
 import urllib.parse
 import warnings
@@ -591,13 +592,13 @@ def handle_redirect(self, uri: str) -> None:
 
     # async for ... in connect(...):
 
-    BACKOFF_MIN = 1.92
-    BACKOFF_MAX = 60.0
-    BACKOFF_FACTOR = 1.618
-    BACKOFF_INITIAL = 5
+    BACKOFF_INITIAL = float(os.environ.get("WEBSOCKETS_BACKOFF_INITIAL_DELAY", "5"))
+    BACKOFF_MIN = float(os.environ.get("WEBSOCKETS_BACKOFF_MIN_DELAY", "3.1"))
+    BACKOFF_MAX = float(os.environ.get("WEBSOCKETS_BACKOFF_MAX_DELAY", "90.0"))
+    BACKOFF_FACTOR = float(os.environ.get("WEBSOCKETS_BACKOFF_FACTOR", "1.618"))
 
     async def __aiter__(self) -> AsyncIterator[WebSocketClientProtocol]:
-        backoff_delay = self.BACKOFF_MIN
+        backoff_delay = self.BACKOFF_MIN / self.BACKOFF_FACTOR
         while True:
             try:
                 async with self as protocol:

tests/test_client.py

@@ -3,6 +3,7 @@
 import unittest.mock
 
 from websockets.client import *
+from websockets.client import backoff
 from websockets.datastructures import Headers
 from websockets.exceptions import InvalidHandshake, InvalidHeader
 from websockets.frames import OP_TEXT, Frame
@@ -613,3 +614,15 @@ def test_client_connection_class(self):
             client = ClientConnection("ws://localhost/")
 
         self.assertIsInstance(client, ClientProtocol)
+
+
+class BackoffTests(unittest.TestCase):
+    def test_backoff(self):
+        backoff_gen = backoff()
+
+        initial_delay = next(backoff_gen)
+        self.assertGreaterEqual(initial_delay, 0)
+        self.assertLess(initial_delay, 5)
+
+        following_delays = [int(next(backoff_gen)) for _ in range(9)]
+        self.assertEqual(following_delays, [3, 5, 8, 13, 21, 34, 55, 89, 90])