Add jitter to exponential retries and clamp retry count

Author: IvanildoBarauna

README.md

@@ -65,7 +65,8 @@ client = ClientBuilder(endpoint="https://api.example.com"
                         ,connection_timeout=10
                         ,headers=headers
                         ,retries=5
-                        ,initial_delay=10)
+                        ,initial_delay=10
+                        ,jitter=0.5)
 
 
 # Get data from the API
@@ -79,10 +80,11 @@ print(df)
 ```
 
 ## Important notes:
-* **Opcionals Parameters:** The params timeout, retry_strategy and headers are opcionals.
+* **Opcionals Parameters:** The params timeout, retry_strategy, headers and jitter are opcionals.
 * **Default Params Value:** By default the quantity of retries is 3 and the time between retries is 1 second, but you can define manually.
-* **Max Of Retries:** For security of API Server there is a limit for quantity of retries, actually this value is 5, this value is defined in lib constant. You can inform any value in RETRIES param, but the lib only will try 5x.
+* **Max Of Retries:** For security of API Server there is a limit for quantity of retries, actually this value is 5, this value is defined in lib constant. You can inform any value in RETRIES param, but the lib only will try 5x and will log a warning if a higher value is informed.
 * **Exponential Retry Strategy:** The increment of time between retries is time passed in **initial_delay** param * 2 * the retry_number, e.g with initial_delay=2
+* **Jitter Parameter:** When using the exponential strategy you can define a **jitter** value to add a random wait time between 0 and the informed jitter. This helps to avoid thundering herd effects.
 
     RetryNumber  | WaitingTime
     ------------ | -----------

src/api_to_dataframe/controller/client_builder.py

@@ -1,5 +1,6 @@
 from api_to_dataframe.models.retainer import retry_strategies, Strategies
 from api_to_dataframe.models.get_data import GetData
+from api_to_dataframe.utils import Constants
 from api_to_dataframe.utils.logger import logger
 
 
@@ -12,6 +13,7 @@ def __init__(  # pylint: disable=too-many-positional-arguments,too-many-argument
         retries: int = 3,
         initial_delay: int = 1,
         connection_timeout: int = 1,
+        jitter: float = 0.0,
     ):
         """
         Initializes the ClientBuilder object.
@@ -23,12 +25,14 @@ def __init__(  # pylint: disable=too-many-positional-arguments,too-many-argument
             retries (int): The number of times to retry a failed request. Defaults to 3.
             initial_delay (int): The delay between retries in seconds. Defaults to 1.
             connection_timeout (int): The timeout for the connection in seconds. Defaults to 1.
+            jitter (float): Additional random jitter in seconds applied to exponential retries.
 
         Raises:
             ValueError: If endpoint is an empty string.
             ValueError: If retries is not a non-negative integer.
             ValueError: If delay is not a non-negative integer.
             ValueError: If connection_timeout is not a non-negative integer.
+            ValueError: If jitter is negative or not a numeric value.
         """
 
         if headers is None:
@@ -49,13 +53,25 @@ def __init__(  # pylint: disable=too-many-positional-arguments,too-many-argument
             error_msg = "connection_timeout must be a non-negative integer"
             logger.error(error_msg)
             raise ValueError
+        if not isinstance(jitter, (int, float)) or jitter < 0:
+            error_msg = "jitter must be a non-negative number"
+            logger.error(error_msg)
+            raise ValueError
 
         self.endpoint = endpoint
         self.retry_strategy = retry_strategy
         self.connection_timeout = connection_timeout
         self.headers = headers
-        self.retries = retries
+        clamped_retries = min(retries, Constants.MAX_OF_RETRIES)
+        if retries != clamped_retries:
+            logger.warning(
+                "Retry count %s exceeds global maximum of %s. Clamping to the allowed value.",
+                retries,
+                Constants.MAX_OF_RETRIES,
+            )
+        self.retries = clamped_retries
         self.delay = initial_delay
+        self.jitter = float(jitter)
 
     @retry_strategies
     def get_api_data(self):

src/api_to_dataframe/models/retainer.py

@@ -1,3 +1,4 @@
+import random
 import time
 from enum import Enum
 
@@ -15,11 +16,15 @@ class Strategies(Enum):
 def retry_strategies(func):
     def wrapper(*args, **kwargs):  # pylint: disable=inconsistent-return-statements
         retry_number = 0
-        while retry_number < args[0].retries:
+        max_allowed_retries = min(args[0].retries, Constants.MAX_OF_RETRIES)
+        while retry_number < max_allowed_retries:
             try:
                 if retry_number > 0:
                     logger.info(
-                        f"Trying for the {retry_number} of {Constants.MAX_OF_RETRIES} retries. Using {args[0].retry_strategy}"
+                        "Trying for the %s of %s retries. Using %s",
+                        retry_number,
+                        max_allowed_retries,
+                        args[0].retry_strategy,
                     )
                 return func(*args, **kwargs)
             except RequestException as e:
@@ -30,10 +35,13 @@ def wrapper(*args, **kwargs):  # pylint: disable=inconsistent-return-statements
                 if args[0].retry_strategy == Strategies.LINEAR_RETRY_STRATEGY:
                     time.sleep(args[0].delay)
                 elif args[0].retry_strategy == Strategies.EXPONENTIAL_RETRY_STRATEGY:
-                    time.sleep(args[0].delay * retry_number)
+                    jitter = 0.0
+                    if getattr(args[0], "jitter", 0) > 0:
+                        jitter = random.uniform(0, args[0].jitter)
+                    time.sleep(args[0].delay * retry_number + jitter)
 
-                if retry_number in (args[0].retries, Constants.MAX_OF_RETRIES):
-                    logger.error(f"Failed after {retry_number} retries")
+                if retry_number >= max_allowed_retries:
+                    logger.error("Failed after %s retries", retry_number)
                     raise e
 
     return wrapper

tests/test_controller_client_builder.py

@@ -7,21 +7,42 @@
 
 @pytest.fixture()
 def client_setup():
-    new_client = ClientBuilder(
-        endpoint="https://economia.awesomeapi.com.br/last/USD-BRL"
-    )
-    return new_client
+    """Create a client with a mocked API endpoint."""
+
+    endpoint = "https://economia.awesomeapi.com.br/last/USD-BRL"
+    mocked_payload = {"USDBRL": {"code": "USD", "codein": "BRL", "bid": "5.0"}}
+    responses_mock = responses.RequestsMock(assert_all_requests_are_fired=False)
+    responses_mock.start()
+    responses_mock.add(responses.GET, endpoint, json=mocked_payload, status=200)
+
+    client = ClientBuilder(endpoint=endpoint)
+    yield client
+
+    responses_mock.stop()
+    responses_mock.reset()
 
 
 @pytest.fixture()
 def response_setup():
-    new_client = ClientBuilder(
-        endpoint="https://economia.awesomeapi.com.br/last/USD-BRL"
-    )
-    return new_client.get_api_data()
+    """Provide a mocked API response as a dictionary."""
+
+    endpoint = "https://economia.awesomeapi.com.br/last/USD-BRL"
+    mocked_payload = {"USDBRL": {"code": "USD", "codein": "BRL", "bid": "5.0"}}
+    responses_mock = responses.RequestsMock(assert_all_requests_are_fired=False)
+    responses_mock.start()
+    responses_mock.add(responses.GET, endpoint, json=mocked_payload, status=200)
+
+    new_client = ClientBuilder(endpoint=endpoint)
+    response = new_client.get_api_data()
+
+    responses_mock.stop()
+    responses_mock.reset()
+
+    return response
 
 
 def test_constructor_raises():
+    """Ensure constructor validates required arguments."""
     with pytest.raises(ValueError):
         ClientBuilder(endpoint="")
 
@@ -59,6 +80,7 @@ def test_constructor_raises():
 
 
 def test_constructor_with_param(client_setup):  # pylint: disable=redefined-outer-name
+    """Verify constructor assigns provided endpoint."""
     expected_result = "https://economia.awesomeapi.com.br/last/USD-BRL"
     new_client = client_setup
     assert new_client.endpoint == expected_result
@@ -88,12 +110,14 @@ def test_constructor_with_retry_strategy():
 
 
 def test_response_to_json(client_setup):  # pylint: disable=redefined-outer-name
+    """Validate the client converts the mocked response to a dict."""
     new_client = client_setup
     response = new_client.get_api_data()  # pylint: disable=protected-access
     assert isinstance(response, dict)
 
 
 def test_to_dataframe(response_setup):  # pylint: disable=redefined-outer-name
+    """Confirm the API response can be converted into a DataFrame."""
     df = ClientBuilder.api_to_dataframe(response_setup)
     assert isinstance(df, pd.DataFrame)
 

tests/test_models_retainer.py

@@ -1,68 +1,147 @@
-import time
+import logging
 import requests
 import pytest
 
 from api_to_dataframe import ClientBuilder, RetryStrategies
+from api_to_dataframe.utils import Constants
 
-# from api_to_dataframe.utils import Constants
 
+def _raise_request_exception(*args, **kwargs):
+    raise requests.exceptions.RequestException("boom")
+
+
+def test_linear_strategy(monkeypatch):
+    """Ensure the linear strategy sleeps for a constant interval between retries."""
+
+    monkeypatch.setattr(
+        "src.api_to_dataframe.models.get_data.requests.get",
+        _raise_request_exception,
+    )
+    sleep_calls = []
+
+    def fake_sleep(delay):
+        sleep_calls.append(delay)
+
+    monkeypatch.setattr("src.api_to_dataframe.models.retainer.time.sleep", fake_sleep)
 
-def test_linear_strategy():
-    endpoint = "https://api-to-dataframe/"
-    max_retries = 2
     client = ClientBuilder(
-        endpoint=endpoint,
+        endpoint="https://api-to-dataframe/",
         retry_strategy=RetryStrategies.LINEAR_RETRY_STRATEGY,
-        retries=max_retries,
+        retries=2,
         initial_delay=1,
         connection_timeout=1,
     )
 
-    retry_number = 0
+    with pytest.raises(requests.exceptions.RequestException):
+        client.get_api_data()
+
+    assert sleep_calls == [1, 1]
+
 
-    while retry_number < max_retries:
-        start = time.time()
-        try:
-            client.get_api_data()
-        except requests.exceptions.RequestException:
-            end = time.time()
-            assert end - start >= client.delay
-            retry_number += 1
+def test_no_retry_strategy(monkeypatch):
+    """Validate that no retry strategy raises immediately without sleeping."""
 
-    assert retry_number == max_retries
+    monkeypatch.setattr(
+        "src.api_to_dataframe.models.get_data.requests.get",
+        _raise_request_exception,
+    )
+    sleep_calls = []
+
+    def fake_sleep(delay):
+        sleep_calls.append(delay)
 
+    monkeypatch.setattr("src.api_to_dataframe.models.retainer.time.sleep", fake_sleep)
 
-def test_no_retry_strategy():
-    endpoint = "https://api-to-dataframe/"
     client = ClientBuilder(
-        endpoint=endpoint,
+        endpoint="https://api-to-dataframe/",
         retry_strategy=RetryStrategies.NO_RETRY_STRATEGY,
     )
 
     with pytest.raises(requests.exceptions.RequestException):
         client.get_api_data()
 
+    assert sleep_calls == []
+
+
+def test_exponential_strategy(monkeypatch):
+    """Ensure the exponential strategy multiplies the delay by the retry attempt."""
+
+    monkeypatch.setattr(
+        "src.api_to_dataframe.models.get_data.requests.get",
+        _raise_request_exception,
+    )
+    sleep_calls = []
+
+    def fake_sleep(delay):
+        sleep_calls.append(delay)
+
+    monkeypatch.setattr("src.api_to_dataframe.models.retainer.time.sleep", fake_sleep)
 
-def test_exponential_strategy():
-    endpoint = "https://api-to-dataframe/"
-    max_retries = 2
     client = ClientBuilder(
-        endpoint=endpoint,
+        endpoint="https://api-to-dataframe/",
         retry_strategy=RetryStrategies.EXPONENTIAL_RETRY_STRATEGY,
-        retries=max_retries,
+        retries=3,
         initial_delay=1,
         connection_timeout=1,
     )
 
-    retry_number = 0
+    with pytest.raises(requests.exceptions.RequestException):
+        client.get_api_data()
+
+    assert sleep_calls == [1, 2, 3]
+
 
-    while retry_number < max_retries:
-        start = time.time()
-        try:
-            client.get_api_data()
-        except requests.exceptions.RequestException:
-            end = time.time()
-            assert end - start >= client.delay * retry_number
-            retry_number += 1
+def test_global_retry_cap_applied(caplog):
+    """Check that the global retry cap is enforced and a warning is logged when clamped."""
+
+    caplog.set_level(logging.WARNING)
+
+    client = ClientBuilder(
+        endpoint="https://api-to-dataframe/",
+        retry_strategy=RetryStrategies.LINEAR_RETRY_STRATEGY,
+        retries=Constants.MAX_OF_RETRIES + 2,
+        initial_delay=1,
+        connection_timeout=1,
+    )
+
+    assert client.retries == Constants.MAX_OF_RETRIES
+    assert "Clamping" in caplog.text
+
+
+def test_exponential_strategy_uses_jitter(monkeypatch):
+    """Verify that exponential retries add the configured jitter to the sleep duration."""
+
+    monkeypatch.setattr(
+        "src.api_to_dataframe.models.get_data.requests.get",
+        _raise_request_exception,
+    )
+    sleep_calls = []
+
+    def fake_sleep(delay):
+        sleep_calls.append(delay)
+
+    monkeypatch.setattr("src.api_to_dataframe.models.retainer.time.sleep", fake_sleep)
+
+    jitter_values = [0.5, 0.25]
+
+    def fake_uniform(_, __):
+        return jitter_values.pop(0)
+
+    monkeypatch.setattr(
+        "src.api_to_dataframe.models.retainer.random.uniform",
+        fake_uniform,
+    )
+
+    client = ClientBuilder(
+        endpoint="https://api-to-dataframe/",
+        retry_strategy=RetryStrategies.EXPONENTIAL_RETRY_STRATEGY,
+        retries=2,
+        initial_delay=1,
+        connection_timeout=1,
+        jitter=1.0,
+    )
+
+    with pytest.raises(requests.exceptions.RequestException):
+        client.get_api_data()
 
-    assert retry_number == max_retries
+    assert sleep_calls == [1.5, 2.25]