test_http_retry.py

import typing
from unittest import mock
from unittest.mock import Mock, patch

import pytest
import requests
from requests.exceptions import (
    ChunkedEncodingError,
    ConnectionError,
    ConnectTimeout,
    ReadTimeout,
    RetryError,
    Timeout,
)
from urllib3.exceptions import IncompleteRead, ProtocolError

from fromager import http_retry


class TestRetryHTTPAdapter:
    """Test cases for RetryHTTPAdapter class."""

    def test_init_with_default_config(self) -> None:
        """Test adapter initialization with default configuration."""
        adapter = http_retry.RetryHTTPAdapter()
        assert adapter.timeout == 60.0
        assert adapter.backoff_factor == 1.0
        assert adapter.max_backoff == 60.0

    def test_init_with_custom_config(self) -> None:
        """Test adapter initialization with custom configuration."""
        custom_config = {
            "total": 3,
            "backoff_factor": 2.0,
            "status_forcelist": [502, 503],
            "allowed_methods": ["GET", "POST"],
            "raise_on_status": True,
        }
        adapter = http_retry.RetryHTTPAdapter(retry_config=custom_config, timeout=30.0)
        assert adapter.timeout == 30.0
        assert adapter.backoff_factor == 2.0

    def test_init_with_invalid_config_types(self) -> None:
        """Test adapter handles invalid configuration types gracefully."""
        invalid_config = {
            "total": "invalid",
            "backoff_factor": "invalid",
            "status_forcelist": "invalid",
            "allowed_methods": "invalid",
            "raise_on_status": "invalid",
        }
        adapter = http_retry.RetryHTTPAdapter(retry_config=invalid_config)
        # Should use defaults when invalid types are provided
        assert adapter.backoff_factor == 1.0

    @patch("fromager.http_retry.RetryHTTPAdapter._handle_github_rate_limit")
    @patch("requests.adapters.HTTPAdapter.send")
    def test_send_successful_response(
        self, mock_super_send: typing.Any, mock_github_handler: typing.Any
    ) -> None:
        """Test successful HTTP request without retries."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"

        response = Mock(spec=requests.Response)
        response.status_code = 200
        mock_super_send.return_value = response

        result = adapter.send(request)

        assert result == response
        mock_super_send.assert_called_once()
        mock_github_handler.assert_not_called()

    @patch("time.sleep")
    @patch("requests.adapters.HTTPAdapter.send")
    def test_send_retries_on_server_errors(
        self, mock_super_send: typing.Any, mock_sleep: typing.Any
    ) -> None:
        """Test retry behavior on server error status codes."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"

        error_response = Mock(spec=requests.Response)
        error_response.status_code = 502
        success_response = Mock(spec=requests.Response)
        success_response.status_code = 200

        mock_super_send.side_effect = [error_response, success_response]

        result = adapter.send(request)

        assert result == success_response
        assert mock_super_send.call_count == 2
        mock_sleep.assert_called_once()

    @patch("fromager.http_retry.time.time", return_value=100.0)
    @patch("time.sleep")
    @patch("requests.adapters.HTTPAdapter.send")
    def test_send_github_rate_limit_handling(
        self,
        mock_super_send: typing.Any,
        mock_sleep: typing.Any,
        mock_time: typing.Any,
    ) -> None:
        """Test GitHub API rate limit handling."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://api.github.com/repos/test"

        rate_limit_response = Mock(spec=requests.Response)
        rate_limit_response.status_code = 403
        rate_limit_response.text = "API rate limit exceeded"
        rate_limit_response.headers = {"X-RateLimit-Reset": str(160)}
        rate_limit_response.request = request

        success_response = Mock(spec=requests.Response)
        success_response.status_code = 200

        mock_super_send.side_effect = [rate_limit_response, success_response]

        result = adapter.send(request)

        assert result == success_response
        assert mock_super_send.call_count == 2
        mock_sleep.assert_called_once()

    @patch("time.sleep")
    @patch("requests.adapters.HTTPAdapter.send")
    def test_send_retries_on_connection_error(
        self, mock_super_send: typing.Any, mock_sleep: typing.Any
    ) -> None:
        """Test retry behavior on connection errors."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"

        success_response = Mock(spec=requests.Response)
        success_response.status_code = 200

        # First call raises ConnectionError, second succeeds
        mock_super_send.side_effect = [
            ConnectionError("Connection failed"),
            success_response,
        ]

        result = adapter.send(request)

        assert result == success_response
        assert mock_super_send.call_count == 2
        mock_sleep.assert_called_once()

    @patch("requests.adapters.HTTPAdapter.send")
    def test_send_exhausts_retries_and_raises(
        self, mock_super_send: typing.Any
    ) -> None:
        """Test that retries are exhausted and exception is raised."""
        adapter = http_retry.RetryHTTPAdapter(retry_config={"total": 1})
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"

        mock_super_send.side_effect = ConnectionError("Persistent connection error")

        with pytest.raises(ConnectionError):
            adapter.send(request)

    @patch("fromager.http_retry.time.time", return_value=100.0)
    def test_handle_github_rate_limit_with_short_reset(
        self, mock_time: typing.Any
    ) -> None:
        """Test GitHub rate limit sleeps and retries when reset is soon."""
        adapter = http_retry.RetryHTTPAdapter()
        response = Mock(spec=requests.Response)
        response.headers = {"X-RateLimit-Reset": str(110)}
        response.request = Mock()
        response.request.url = "https://api.github.com"

        with patch("time.sleep") as mock_sleep:
            adapter._handle_github_rate_limit(response, 0, 3)
            mock_sleep.assert_called_once_with(15)  # 110 - 100 + 5

    @patch("fromager.http_retry.time.time", return_value=100.0)
    def test_handle_github_rate_limit_raises_on_long_wait(
        self, mock_time: typing.Any
    ) -> None:
        """Test GitHub rate limit raises immediately when reset is far away."""
        adapter = http_retry.RetryHTTPAdapter()
        response = Mock(spec=requests.Response)
        reset_in = http_retry.GITHUB_RATE_LIMIT_MAX_WAIT + 100
        response.headers = {"X-RateLimit-Reset": str(100 + reset_in)}
        response.request = Mock()
        response.request.url = "https://api.github.com/repos/test"

        with pytest.raises(http_retry.GitHubRateLimitError, match="GITHUB_TOKEN"):
            adapter._handle_github_rate_limit(response, 0, 3)

    @patch("fromager.http_retry.time.time", return_value=100.0)
    def test_handle_github_rate_limit_at_threshold_boundary(
        self, mock_time: typing.Any
    ) -> None:
        """Test wait_time exactly at threshold sleeps instead of raising."""
        adapter = http_retry.RetryHTTPAdapter()
        response = Mock(spec=requests.Response)
        # wait_time = reset - current + 5 = threshold exactly
        reset_ts = 100 + http_retry.GITHUB_RATE_LIMIT_MAX_WAIT - 5
        response.headers = {"X-RateLimit-Reset": str(reset_ts)}
        response.request = Mock()
        response.request.url = "https://api.github.com/repos/test"

        with patch("time.sleep") as mock_sleep:
            adapter._handle_github_rate_limit(response, 0, 3)
            mock_sleep.assert_called_once_with(http_retry.GITHUB_RATE_LIMIT_MAX_WAIT)

    @patch("fromager.http_retry.time.time", return_value=100.0)
    def test_handle_github_rate_limit_raises_on_max_attempts(
        self, mock_time: typing.Any
    ) -> None:
        """Test GitHub rate limit raises when retries are exhausted."""
        adapter = http_retry.RetryHTTPAdapter()
        response = Mock(spec=requests.Response)
        response.headers = {"X-RateLimit-Reset": str(110)}
        response.request = Mock()
        response.request.url = "https://api.github.com/repos/test"

        with pytest.raises(http_retry.GitHubRateLimitError, match="GITHUB_TOKEN"):
            adapter._handle_github_rate_limit(response, 2, 3)

    def test_handle_github_rate_limit_raises_on_invalid_header_at_max_attempts(
        self,
    ) -> None:
        """Test raises with 'Reset time unknown' when header is unparseable and retries exhausted."""
        adapter = http_retry.RetryHTTPAdapter()
        response = Mock(spec=requests.Response)
        response.headers = {"X-RateLimit-Reset": "garbage"}
        response.request = Mock()
        response.request.url = "https://api.github.com/repos/test"

        with pytest.raises(http_retry.GitHubRateLimitError, match="Reset time unknown"):
            adapter._handle_github_rate_limit(response, 2, 3)

    def test_handle_github_rate_limit_without_reset_header(self) -> None:
        """Test GitHub rate limit uses exponential backoff when reset header is missing."""
        adapter = http_retry.RetryHTTPAdapter()
        response = Mock(spec=requests.Response)
        response.headers = {}
        response.request = Mock()
        response.request.url = "https://api.github.com"

        with patch("time.sleep") as mock_sleep:
            adapter._handle_github_rate_limit(response, 0, 3)
            mock_sleep.assert_called_once()

    def test_handle_retryable_exception(self) -> None:
        """Test handling of retryable exceptions."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"
        exception = ConnectionError("Test error")

        with patch("time.sleep") as mock_sleep:
            adapter._handle_retryable_exception(exception, request, 0, 3)
            mock_sleep.assert_called_once()

    def test_handle_retryable_exception_max_attempts(self) -> None:
        """Test handling retryable exception at max attempts."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"
        exception = ConnectionError("Test error")

        with patch("time.sleep") as mock_sleep:
            adapter._handle_retryable_exception(exception, request, 2, 3)
            mock_sleep.assert_not_called()


class TestCreateRetrySession:
    """Test cases for create_retry_session function."""

    def test_create_retry_session_default(self) -> None:
        """Test creating a retry session with default configuration."""
        session = http_retry.create_retry_session()
        assert isinstance(session, requests.Session)
        assert "http://" in session.adapters
        assert "https://" in session.adapters

    def test_create_retry_session_custom_config(self) -> None:
        """Test creating a retry session with custom configuration."""
        custom_config = {"total": 3, "backoff_factor": 2.0}
        session = http_retry.create_retry_session(
            retry_config=custom_config, timeout=30.0
        )
        assert isinstance(session, requests.Session)

    def test_create_retry_session_basic(self) -> None:
        """Test basic session creation."""
        session = http_retry.create_retry_session()
        assert isinstance(session.get_adapter("http://"), http_retry.RetryHTTPAdapter)
        assert isinstance(session.get_adapter("https://"), http_retry.RetryHTTPAdapter)
        assert "Authorization" not in session.headers


class TestRetryOnExceptionDecorator:
    """Test cases for retry_on_exception decorator."""

    def test_retry_decorator_success_on_first_attempt(self) -> None:
        """Test decorator when function succeeds on first attempt."""

        @http_retry.retry_on_exception(max_attempts=3)
        def successful_function() -> str:
            return "success"

        result = successful_function()
        assert result == "success"

    def test_retry_decorator_success_after_retries(self) -> None:
        """Test decorator when function succeeds after retries."""
        call_count = 0

        @http_retry.retry_on_exception(max_attempts=3, backoff_factor=0.01)
        def failing_then_succeeding_function() -> str:
            nonlocal call_count
            call_count += 1
            if call_count < 3:
                raise ConnectionError("Temporary failure")
            return "success"

        with patch("time.sleep"):
            result = failing_then_succeeding_function()
            assert result == "success"
            assert call_count == 3

    def test_retry_decorator_exhausts_attempts(self) -> None:
        """Test decorator when all retry attempts are exhausted."""

        @http_retry.retry_on_exception(max_attempts=2, backoff_factor=0.01)
        def always_failing_function() -> None:
            raise ConnectionError("Persistent failure")

        with patch("time.sleep"):
            with pytest.raises(ConnectionError):
                always_failing_function()

    def test_retry_decorator_non_retryable_exception(self) -> None:
        """Test decorator with non-retryable exception."""

        @http_retry.retry_on_exception(exceptions=(ConnectionError,), max_attempts=3)
        def function_with_non_retryable_exception() -> None:
            raise ValueError("Non-retryable error")

        with pytest.raises(ValueError):
            function_with_non_retryable_exception()

    def test_retry_decorator_custom_exceptions(self) -> None:
        """Test decorator with custom exception types."""

        @http_retry.retry_on_exception(
            exceptions=(ValueError, TypeError), max_attempts=2, backoff_factor=0.01
        )
        def function_with_custom_exceptions() -> None:
            raise ValueError("Custom retryable error")

        with patch("time.sleep"):
            with pytest.raises(ValueError):
                function_with_custom_exceptions()

    def test_retry_decorator_with_function_arguments(self) -> None:
        """Test decorator preserves function arguments."""

        @http_retry.retry_on_exception(max_attempts=2)
        def function_with_args(
            arg1: typing.Any, arg2: typing.Any, kwarg1: typing.Any = None
        ) -> str:
            return f"{arg1}-{arg2}-{kwarg1}"

        result = function_with_args("a", "b", kwarg1="c")
        assert result == "a-b-c"


class TestGetRetrySession:
    """Test cases for get_retry_session function."""

    def test_get_retry_session(self) -> None:
        """Test getting a pre-configured retry session."""
        session = http_retry.get_retry_session()
        assert isinstance(session, requests.Session)
        assert "http://" in session.adapters
        assert "https://" in session.adapters


class TestDefaultRetryConfig:
    """Test cases for default retry configuration."""

    def test_default_retry_config_values(self) -> None:
        """Test that default retry configuration has expected values."""
        config = http_retry.DEFAULT_RETRY_CONFIG
        assert config["total"] == 5
        assert config["backoff_factor"] == 1.0
        status_forcelist = config["status_forcelist"]
        assert isinstance(status_forcelist, list)
        assert 429 in status_forcelist
        assert 502 in status_forcelist
        allowed_methods = config["allowed_methods"]
        assert isinstance(allowed_methods, list)
        assert "GET" in allowed_methods
        assert config["raise_on_status"] is False


class TestRetryableExceptions:
    """Test cases for retryable exceptions tuple."""

    def test_retryable_exceptions_contains_expected_types(self) -> None:
        """Test that RETRYABLE_EXCEPTIONS contains expected exception types."""
        exceptions = http_retry.RETRYABLE_EXCEPTIONS
        assert ConnectionError in exceptions
        assert Timeout in exceptions
        assert ChunkedEncodingError in exceptions
        assert IncompleteRead in exceptions
        assert ProtocolError in exceptions
        assert RetryError in exceptions
        assert ConnectTimeout in exceptions
        assert ReadTimeout in exceptions


class TestIntegration:
    """Integration test cases."""

    def test_end_to_end_retry_session(self) -> None:
        """Test end-to-end usage of retry session."""
        # Test that we can create a session and access its adapters
        session = http_retry.create_retry_session()

        # Verify session has retry adapters mounted
        assert isinstance(session.adapters["http://"], http_retry.RetryHTTPAdapter)
        assert isinstance(session.adapters["https://"], http_retry.RetryHTTPAdapter)

        # Verify session has proper timeout configuration
        http_adapter = session.adapters["https://"]
        assert http_adapter.timeout == 60.0

    def test_adapter_with_various_retryable_exceptions(self) -> None:
        """Test adapter handles various retryable exceptions."""
        adapter = http_retry.RetryHTTPAdapter(retry_config={"total": 1})
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"

        # Test each retryable exception type
        retryable_exceptions = [
            ConnectionError("Connection failed"),
            Timeout("Request timed out"),
            ChunkedEncodingError("Chunked encoding error"),
            IncompleteRead(partial=10, expected=20),
            ProtocolError("Protocol error"),
        ]

        for exception in retryable_exceptions:
            with patch("requests.adapters.HTTPAdapter.send") as mock_send:
                mock_send.side_effect = exception
                with patch("time.sleep"):
                    with pytest.raises(type(exception)):
                        adapter.send(request)

    @patch("time.sleep")
    @patch("random.uniform", return_value=0.5)
    def test_backoff_calculation(
        self, mock_random: typing.Any, mock_sleep: typing.Any
    ) -> None:
        """Test backoff time calculation with jitter."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://example.com"
        exception = ConnectionError("Test error")

        adapter._handle_retryable_exception(exception, request, 1, 5)

        # Expected: min(2^1 + 0.5, 60) = min(2.5, 60) = 2.5
        mock_sleep.assert_called_once_with(2.5)


# Test standalone functions
def test_default_retry_config_structure() -> None:
    """Test that DEFAULT_RETRY_CONFIG has the correct structure."""
    config = http_retry.DEFAULT_RETRY_CONFIG
    expected_keys = {
        "total",
        "backoff_factor",
        "status_forcelist",
        "allowed_methods",
        "raise_on_status",
    }
    assert set(config.keys()) == expected_keys


def test_retryable_exceptions_tuple_is_not_empty() -> None:
    """Test that RETRYABLE_EXCEPTIONS is not empty."""
    assert len(http_retry.RETRYABLE_EXCEPTIONS) > 0


@patch("time.sleep")
@patch("random.uniform", return_value=0.1)
def test_retry_decorator_backoff_timing(
    mock_random: typing.Any, mock_sleep: typing.Any
) -> None:
    """Test retry decorator backoff timing calculation."""
    call_count = 0

    @http_retry.retry_on_exception(max_attempts=3, backoff_factor=2.0, max_backoff=10.0)
    def failing_function() -> str:
        nonlocal call_count
        call_count += 1
        if call_count < 3:
            raise ConnectionError("Temporary failure")
        return "success"

    result = failing_function()

    assert result == "success"
    assert call_count == 3
    # Check that sleep was called with expected backoff times
    expected_calls = [
        mock.call(2.1),  # 2.0 * (2^0) + 0.1 = 2.1
        mock.call(4.1),  # 2.0 * (2^1) + 0.1 = 4.1
    ]
    mock_sleep.assert_has_calls(expected_calls)


@patch("fromager.http_retry.logger")
def test_adapter_logging_on_retry(mock_logger: typing.Any) -> None:
    """Test that appropriate logging occurs during retries."""
    adapter = http_retry.RetryHTTPAdapter()
    request = Mock(spec=requests.PreparedRequest)
    request.url = "https://example.com"
    exception = ConnectionError("Test error")

    with patch("time.sleep"):
        adapter._handle_retryable_exception(exception, request, 0, 3)

    mock_logger.warning.assert_called_once()
    call_args = mock_logger.warning.call_args
    assert len(call_args[0]) > 1
    assert "Request failed for %s" in call_args[0][0]
    assert "https://example.com" in call_args[0]


@patch("fromager.http_retry.logger")
def test_adapter_logging_on_github_rate_limit(mock_logger: typing.Any) -> None:
    """Test logging during GitHub rate limit handling."""
    adapter = http_retry.RetryHTTPAdapter()
    response = Mock(spec=requests.Response)
    response.headers = {}
    response.request = Mock()
    response.request.url = "https://api.github.com"

    with patch("time.sleep"):
        adapter._handle_github_rate_limit(response, 0, 3)

    mock_logger.warning.assert_called_once()
    args = mock_logger.warning.call_args[0]
    assert "GitHub API rate limit hit" in args[0]


class TestGitHubRateLimitError:
    """Test cases for GitHubRateLimitError behavior."""

    def test_is_request_exception(self) -> None:
        """Test that GitHubRateLimitError is a RequestException subclass."""
        err = http_retry.GitHubRateLimitError("test")
        assert isinstance(err, requests.exceptions.RequestException)

    def test_not_in_retryable_exceptions(self) -> None:
        """Test that GitHubRateLimitError is not caught by RETRYABLE_EXCEPTIONS."""
        err = http_retry.GitHubRateLimitError("test")
        assert not isinstance(err, http_retry.RETRYABLE_EXCEPTIONS)

    @patch("fromager.http_retry.time.time", return_value=100.0)
    @patch("time.sleep")
    @patch("requests.adapters.HTTPAdapter.send")
    def test_send_raises_on_long_rate_limit(
        self,
        mock_super_send: typing.Any,
        mock_sleep: typing.Any,
        mock_time: typing.Any,
    ) -> None:
        """Test that send() raises GitHubRateLimitError for long rate limit waits."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://api.github.com/repos/test"

        rate_limit_response = Mock(spec=requests.Response)
        rate_limit_response.status_code = 403
        rate_limit_response.text = "API rate limit exceeded"
        rate_limit_response.headers = {"X-RateLimit-Reset": str(3700)}
        rate_limit_response.request = request

        mock_super_send.return_value = rate_limit_response

        with pytest.raises(http_retry.GitHubRateLimitError, match="GITHUB_TOKEN"):
            adapter.send(request)

        mock_sleep.assert_not_called()

    @patch("fromager.http_retry.time.time", return_value=100.0)
    @patch("time.sleep")
    @patch("requests.adapters.HTTPAdapter.send")
    def test_send_retries_on_short_rate_limit(
        self,
        mock_super_send: typing.Any,
        mock_sleep: typing.Any,
        mock_time: typing.Any,
    ) -> None:
        """Test that send() sleeps and retries for short rate limit waits."""
        adapter = http_retry.RetryHTTPAdapter()
        request = Mock(spec=requests.PreparedRequest)
        request.url = "https://api.github.com/repos/test"

        rate_limit_response = Mock(spec=requests.Response)
        rate_limit_response.status_code = 403
        rate_limit_response.text = "API rate limit exceeded"
        rate_limit_response.headers = {"X-RateLimit-Reset": str(130)}
        rate_limit_response.request = request

        success_response = Mock(spec=requests.Response)
        success_response.status_code = 200

        mock_super_send.side_effect = [rate_limit_response, success_response]

        result = adapter.send(request)

        assert result == success_response
        mock_sleep.assert_called_once()

    @patch("fromager.http_retry.time.time", return_value=100.0)
    def test_error_message_includes_reset_time(self, mock_time: typing.Any) -> None:
        """Test that the error message includes the reset wait time."""
        adapter = http_retry.RetryHTTPAdapter()
        response = Mock(spec=requests.Response)
        response.headers = {"X-RateLimit-Reset": str(3700)}
        response.request = Mock()
        response.request.url = "https://api.github.com/repos/test"

        with pytest.raises(http_retry.GitHubRateLimitError) as exc_info:
            adapter._handle_github_rate_limit(response, 0, 3)

        msg = str(exc_info.value)
        assert "Reset in 3605s" in msg
        assert "GITHUB_TOKEN" in msg
        assert "5000 requests/hour" in msg