BanGUI/backend/tests/test_utils/test_client_ip.py

"""Tests for client IP extraction with proxy support."""

from __future__ import annotations

from unittest.mock import MagicMock

import pytest

from app.utils.client_ip import _is_trusted_proxy, get_client_ip


class TestGetClientIp:
    """Tests for get_client_ip function."""

    def test_returns_immediate_ip_when_no_trusted_proxies(self) -> None:
        """When no trusted proxies are configured, returns immediate IP."""
        request = MagicMock()
        request.client.host = "192.168.1.100"
        request.headers.get.return_value = ""

        result = get_client_ip(request, trusted_proxies=None)

        assert result == "192.168.1.100"

    def test_returns_immediate_ip_when_trusted_proxies_empty(self) -> None:
        """When trusted_proxies list is empty, returns immediate IP."""
        request = MagicMock()
        request.client.host = "192.168.1.100"
        request.headers.get.return_value = ""

        result = get_client_ip(request, trusted_proxies=[])

        assert result == "192.168.1.100"

    def test_returns_immediate_ip_when_not_from_proxy(self) -> None:
        """When immediate IP is not a trusted proxy, ignores forwarded headers."""
        request = MagicMock()
        request.client.host = "203.0.113.1"  # random public IP
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "192.168.1.50",
            "X-Real-IP": "192.168.1.60",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["10.0.0.1"])

        assert result == "203.0.113.1"

    def test_returns_forwarded_for_when_from_trusted_ip(self) -> None:
        """When from trusted proxy IP, extracts X-Forwarded-For header."""
        request = MagicMock()
        request.client.host = "10.0.0.1"  # trusted proxy IP
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "203.0.113.100",
            "X-Real-IP": "203.0.113.200",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["10.0.0.1"])

        assert result == "203.0.113.100"

    def test_returns_first_ip_from_forwarded_for_chain(self) -> None:
        """When X-Forwarded-For has multiple IPs, uses the first (leftmost)."""
        request = MagicMock()
        request.client.host = "10.0.0.1"
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "203.0.113.100, 10.0.0.2, 10.0.0.3",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["10.0.0.1"])

        assert result == "203.0.113.100"

    def test_returns_real_ip_when_forwarded_for_missing(self) -> None:
        """Falls back to X-Real-IP when X-Forwarded-For is absent."""
        request = MagicMock()
        request.client.host = "10.0.0.1"
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Real-IP": "203.0.113.200",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["10.0.0.1"])

        assert result == "203.0.113.200"

    def test_returns_immediate_ip_when_no_forwarded_headers(self) -> None:
        """When proxy is trusted but no forwarded headers, returns immediate IP."""
        request = MagicMock()
        request.client.host = "10.0.0.1"
        request.headers.get.return_value = ""

        result = get_client_ip(request, trusted_proxies=["10.0.0.1"])

        assert result == "10.0.0.1"

    def test_returns_default_when_no_client_info(self) -> None:
        """When request.client is None, returns default IP."""
        request = MagicMock()
        request.client = None

        result = get_client_ip(request)

        assert result == "0.0.0.0"

    def test_strips_whitespace_from_headers(self) -> None:
        """Whitespace in headers is properly stripped."""
        request = MagicMock()
        request.client.host = "10.0.0.1"
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "  203.0.113.100  ",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["10.0.0.1"])

        assert result == "203.0.113.100"

    def test_trusts_ip_in_cidr_range(self) -> None:
        """Trusts proxy when its IP falls within configured CIDR range."""
        request = MagicMock()
        request.client.host = "10.0.0.50"  # within 10.0.0.0/8
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "203.0.113.100",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["10.0.0.0/8"])

        assert result == "203.0.113.100"

    def test_rejects_ip_outside_cidr_range(self) -> None:
        """Rejects proxy when its IP is outside configured CIDR range."""
        request = MagicMock()
        request.client.host = "192.168.1.1"  # outside 10.0.0.0/8
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "203.0.113.100",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["10.0.0.0/8"])

        assert result == "192.168.1.1"

    def test_handles_multiple_trusted_proxies_and_ranges(self) -> None:
        """Handles mix of individual IPs and CIDR ranges."""
        request = MagicMock()
        request.client.host = "10.0.0.50"
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "203.0.113.100",
        }.get(key, default))

        # Multiple trusted proxies with CIDR ranges
        result = get_client_ip(
            request,
            trusted_proxies=["192.168.1.1", "10.0.0.0/8", "172.16.0.0/12"],
        )

        assert result == "203.0.113.100"

    def test_handles_ipv6_addresses(self) -> None:
        """Handles IPv6 proxy addresses and CIDR ranges."""
        request = MagicMock()
        request.client.host = "2001:db8::1"
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "203.0.113.100",
        }.get(key, default))

        result = get_client_ip(request, trusted_proxies=["2001:db8::/32"])

        assert result == "203.0.113.100"

    def test_handles_mixed_ipv4_and_ipv6(self) -> None:
        """Handles IPv4 and IPv6 in the same trusted_proxies list."""
        request = MagicMock()
        request.client.host = "2001:db8::50"
        request.headers.get = MagicMock(side_effect=lambda key, default="": {
            "X-Forwarded-For": "203.0.113.100",
        }.get(key, default))

        result = get_client_ip(
            request,
            trusted_proxies=["192.168.1.0/24", "2001:db8::/32"],
        )

        assert result == "203.0.113.100"


class TestIsTrustedProxy:
    """Tests for _is_trusted_proxy helper function."""

    def test_matches_exact_ip(self) -> None:
        """Exact IP match is recognized."""
        assert _is_trusted_proxy("192.168.1.1", ["192.168.1.1"])

    def test_rejects_different_ip(self) -> None:
        """Different IP is not recognized."""
        assert not _is_trusted_proxy("192.168.1.2", ["192.168.1.1"])

    def test_matches_ip_in_cidr_range(self) -> None:
        """IP within CIDR range is recognized."""
        assert _is_trusted_proxy("10.0.0.50", ["10.0.0.0/8"])
        assert _is_trusted_proxy("10.255.255.255", ["10.0.0.0/8"])

    def test_rejects_ip_outside_cidr_range(self) -> None:
        """IP outside CIDR range is not recognized."""
        assert not _is_trusted_proxy("11.0.0.1", ["10.0.0.0/8"])
        assert not _is_trusted_proxy("9.255.255.255", ["10.0.0.0/8"])

    def test_handles_multiple_ranges(self) -> None:
        """Checks against all ranges, returns True on first match."""
        result = _is_trusted_proxy(
            "192.168.1.50",
            ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
        )
        assert result is True

    def test_returns_false_when_no_match_in_multiple_ranges(self) -> None:
        """Returns False when IP doesn't match any range."""
        result = _is_trusted_proxy(
            "203.0.113.1",
            ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"],
        )
        assert result is False

    def test_handles_ipv6_single_address(self) -> None:
        """IPv6 single address matching."""
        assert _is_trusted_proxy("2001:db8::1", ["2001:db8::1"])
        assert not _is_trusted_proxy("2001:db8::2", ["2001:db8::1"])

    def test_handles_ipv6_cidr_range(self) -> None:
        """IPv6 CIDR range matching."""
        assert _is_trusted_proxy("2001:db8::50", ["2001:db8::/32"])
        assert _is_trusted_proxy("2001:db8:ffff:ffff:ffff:ffff:ffff:ffff", ["2001:db8::/32"])
        assert not _is_trusted_proxy("2001:db9::1", ["2001:db8::/32"])

    def test_returns_false_for_invalid_ip(self) -> None:
        """Invalid IP format returns False."""
        assert not _is_trusted_proxy("not-an-ip", ["192.168.1.0/24"])

    def test_skips_invalid_trusted_proxies(self) -> None:
        """Invalid entries in trusted_proxies list are skipped."""
        # Should not crash and should check valid entries
        result = _is_trusted_proxy(
            "192.168.1.1",
            ["invalid", "192.168.1.0/24", "also-invalid"],
        )
        assert result is True

    def test_empty_trusted_proxies_list(self) -> None:
        """Empty trusted_proxies list always returns False."""
        assert not _is_trusted_proxy("192.168.1.1", [])

    def test_handles_subnet_boundary_cases(self) -> None:
        """Handles edge cases like /32 (single IP) and /0 (all IPs)."""
        # /32 is single IP
        assert _is_trusted_proxy("10.0.0.1", ["10.0.0.1/32"])
        assert not _is_trusted_proxy("10.0.0.2", ["10.0.0.1/32"])

        # /0 should match any IPv4
        assert _is_trusted_proxy("192.168.1.1", ["0.0.0.0/0"])
        assert _is_trusted_proxy("203.0.113.100", ["0.0.0.0/0"])