fastapi-ipware 0.1.0__tar.gz

fastapi_ipware-0.1.0/PKG-INFO

@@ -0,0 +1,214 @@
+Metadata-Version: 2.3
+Name: fastapi-ipware
+Version: 0.1.0
+Summary: FastAPI/Starlette-native wrapper for python-ipware to get client IP addresses
+Keywords: fastapi,starlette,ipware,ip-address,client-ip,proxy,x-forwarded-for
+Author: Michael Bianco
+Author-email: Michael Bianco <mike@mikebian.co>
+Requires-Dist: python-ipware>=3.0.0
+Requires-Dist: starlette>=0.49.1
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/iloveitaly/fastapi-ipware
+Description-Content-Type: text/markdown
+
+# fastapi-ipware
+
+A FastAPI/Starlette-native wrapper for [python-ipware](https://github.com/un33k/python-ipware) that eliminates the need for WSGI-style header conversion.
+
+## Features
+
+- **Zero conversion overhead** - Headers converted once at initialization, not on every request
+- **FastAPI-native API** - Works directly with FastAPI/Starlette `Request` objects
+- **Customizable precedence** - Easy to configure header priority for your infrastructure
+- **Proxy validation** - Supports trusted proxy lists and proxy count validation
+- **Thin wrapper** - Leverages all the battle-tested logic from python-ipware
+
+## Installation
+
+```bash
+pip install fastapi-ipware
+```
+
+Or with uv:
+
+```bash
+uv add fastapi-ipware
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Request
+from fastapi_ipware import FastAPIIpWare
+
+app = FastAPI()
+ipware = FastAPIIpWare()
+
+@app.get("/")
+async def get_ip(request: Request):
+    ip, trusted = ipware.get_client_ip_from_request(request)
+    
+    if ip:
+        return {
+            "ip": str(ip),
+            "trusted": trusted,
+            "is_public": ip.is_global,
+            "is_private": ip.is_private,
+        }
+    
+    return {"error": "Could not determine IP"}
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from fastapi_ipware import FastAPIIpWare
+
+# Use default configuration (optimized for FastAPI/cloud deployments)
+ipware = FastAPIIpWare()
+
+ip, trusted = ipware.get_client_ip_from_request(request)
+```
+
+### Custom Header Precedence
+
+Customize which headers are checked and in what order:
+
+```python
+# Prioritize Cloudflare headers
+ipware = FastAPIIpWare(
+    precedence=(
+        "CF-Connecting-IP",
+        "X-Forwarded-For",
+        "X-Real-IP",
+    )
+)
+
+# NGINX configuration
+ipware = FastAPIIpWare(
+    precedence=(
+        "X-Real-IP",
+        "X-Forwarded-For",
+    )
+)
+```
+
+### Proxy Count Validation
+
+Validate that requests pass through the expected number of proxies:
+
+```python
+# Expect exactly 1 proxy (e.g., AWS ALB)
+ipware = FastAPIIpWare(proxy_count=1)
+
+# In strict mode, must be exactly 1 proxy
+ip, trusted = ipware.get_client_ip_from_request(request, strict=True)
+
+# In non-strict mode, allow 1 or more proxies
+ip, trusted = ipware.get_client_ip_from_request(request, strict=False)
+```
+
+### Trusted Proxy List
+
+Validate that requests pass through specific trusted proxies:
+
+```python
+# Trust specific proxy IP prefixes
+ipware = FastAPIIpWare(
+    proxy_list=["10.0.", "10.1."]  # AWS internal IPs
+)
+
+ip, trusted = ipware.get_client_ip_from_request(request)
+
+# trusted=True only if request came through specified proxies
+```
+
+### Combined Validation
+
+Use both proxy count and trusted proxy list:
+
+```python
+# Expect 1 proxy from a specific IP range
+ipware = FastAPIIpWare(
+    proxy_count=1,
+    proxy_list=["10.0."]
+)
+```
+
+## Real-World Examples
+
+### AWS Application Load Balancer
+
+```python
+ipware = FastAPIIpWare(
+    proxy_count=1,
+    proxy_list=["10.0."]  # Your VPC CIDR
+)
+```
+
+### Cloudflare
+
+```python
+ipware = FastAPIIpWare(
+    precedence=("CF-Connecting-IP",)
+)
+```
+
+### Multiple Proxies (CDN + Load Balancer)
+
+```python
+ipware = FastAPIIpWare(
+    proxy_count=2,
+    proxy_list=["10.1.", "10.2."]  # CDN and LB IPs
+)
+```
+
+### NGINX Reverse Proxy
+
+```python
+ipware = FastAPIIpWare(
+    precedence=("X-Real-IP", "X-Forwarded-For"),
+    proxy_count=1
+)
+```
+
+## IP Address Types
+
+The returned IP address object has useful properties:
+
+```python
+ip, _ = ipware.get_client_ip_from_request(request)
+
+if ip:
+    print(f"Is public: {ip.is_global}")
+    print(f"Is private: {ip.is_private}")
+    print(f"Is loopback: {ip.is_loopback}")
+    print(f"Is multicast: {ip.is_multicast}")
+```
+
+python-ipware automatically prefers:
+1. Public (global) IPs first
+2. Private IPs second
+3. Loopback IPs last
+
+## Default Header Precedence
+
+The default precedence order is optimized for modern cloud deployments. See the [default precedence configuration](https://github.com/iloveitaly/fastapi-ipware/blob/main/fastapi_ipware/__init__.py#L48-L58) in the source code.
+
+## Why fastapi-ipware?
+
+`python-ipware` expects WSGI-style headers (`HTTP_X_FORWARDED_FOR`), but FastAPI uses natural header names (`X-Forwarded-For`). This wrapper handles the conversion automatically so you don't have to.
+
+## Contributing
+
+Contributions welcome! This is a thin wrapper around python-ipware, so most IP detection logic lives there.
+
+## License
+
+[MIT License](LICENSE.md)
+
+## Credits
+
+Built on top of [python-ipware](https://github.com/un33k/python-ipware) by un33k.

fastapi_ipware-0.1.0/README.md

@@ -0,0 +1,201 @@
+# fastapi-ipware
+
+A FastAPI/Starlette-native wrapper for [python-ipware](https://github.com/un33k/python-ipware) that eliminates the need for WSGI-style header conversion.
+
+## Features
+
+- **Zero conversion overhead** - Headers converted once at initialization, not on every request
+- **FastAPI-native API** - Works directly with FastAPI/Starlette `Request` objects
+- **Customizable precedence** - Easy to configure header priority for your infrastructure
+- **Proxy validation** - Supports trusted proxy lists and proxy count validation
+- **Thin wrapper** - Leverages all the battle-tested logic from python-ipware
+
+## Installation
+
+```bash
+pip install fastapi-ipware
+```
+
+Or with uv:
+
+```bash
+uv add fastapi-ipware
+```
+
+## Quick Start
+
+```python
+from fastapi import FastAPI, Request
+from fastapi_ipware import FastAPIIpWare
+
+app = FastAPI()
+ipware = FastAPIIpWare()
+
+@app.get("/")
+async def get_ip(request: Request):
+    ip, trusted = ipware.get_client_ip_from_request(request)
+    
+    if ip:
+        return {
+            "ip": str(ip),
+            "trusted": trusted,
+            "is_public": ip.is_global,
+            "is_private": ip.is_private,
+        }
+    
+    return {"error": "Could not determine IP"}
+```
+
+## Usage
+
+### Basic Usage
+
+```python
+from fastapi_ipware import FastAPIIpWare
+
+# Use default configuration (optimized for FastAPI/cloud deployments)
+ipware = FastAPIIpWare()
+
+ip, trusted = ipware.get_client_ip_from_request(request)
+```
+
+### Custom Header Precedence
+
+Customize which headers are checked and in what order:
+
+```python
+# Prioritize Cloudflare headers
+ipware = FastAPIIpWare(
+    precedence=(
+        "CF-Connecting-IP",
+        "X-Forwarded-For",
+        "X-Real-IP",
+    )
+)
+
+# NGINX configuration
+ipware = FastAPIIpWare(
+    precedence=(
+        "X-Real-IP",
+        "X-Forwarded-For",
+    )
+)
+```
+
+### Proxy Count Validation
+
+Validate that requests pass through the expected number of proxies:
+
+```python
+# Expect exactly 1 proxy (e.g., AWS ALB)
+ipware = FastAPIIpWare(proxy_count=1)
+
+# In strict mode, must be exactly 1 proxy
+ip, trusted = ipware.get_client_ip_from_request(request, strict=True)
+
+# In non-strict mode, allow 1 or more proxies
+ip, trusted = ipware.get_client_ip_from_request(request, strict=False)
+```
+
+### Trusted Proxy List
+
+Validate that requests pass through specific trusted proxies:
+
+```python
+# Trust specific proxy IP prefixes
+ipware = FastAPIIpWare(
+    proxy_list=["10.0.", "10.1."]  # AWS internal IPs
+)
+
+ip, trusted = ipware.get_client_ip_from_request(request)
+
+# trusted=True only if request came through specified proxies
+```
+
+### Combined Validation
+
+Use both proxy count and trusted proxy list:
+
+```python
+# Expect 1 proxy from a specific IP range
+ipware = FastAPIIpWare(
+    proxy_count=1,
+    proxy_list=["10.0."]
+)
+```
+
+## Real-World Examples
+
+### AWS Application Load Balancer
+
+```python
+ipware = FastAPIIpWare(
+    proxy_count=1,
+    proxy_list=["10.0."]  # Your VPC CIDR
+)
+```
+
+### Cloudflare
+
+```python
+ipware = FastAPIIpWare(
+    precedence=("CF-Connecting-IP",)
+)
+```
+
+### Multiple Proxies (CDN + Load Balancer)
+
+```python
+ipware = FastAPIIpWare(
+    proxy_count=2,
+    proxy_list=["10.1.", "10.2."]  # CDN and LB IPs
+)
+```
+
+### NGINX Reverse Proxy
+
+```python
+ipware = FastAPIIpWare(
+    precedence=("X-Real-IP", "X-Forwarded-For"),
+    proxy_count=1
+)
+```
+
+## IP Address Types
+
+The returned IP address object has useful properties:
+
+```python
+ip, _ = ipware.get_client_ip_from_request(request)
+
+if ip:
+    print(f"Is public: {ip.is_global}")
+    print(f"Is private: {ip.is_private}")
+    print(f"Is loopback: {ip.is_loopback}")
+    print(f"Is multicast: {ip.is_multicast}")
+```
+
+python-ipware automatically prefers:
+1. Public (global) IPs first
+2. Private IPs second
+3. Loopback IPs last
+
+## Default Header Precedence
+
+The default precedence order is optimized for modern cloud deployments. See the [default precedence configuration](https://github.com/iloveitaly/fastapi-ipware/blob/main/fastapi_ipware/__init__.py#L48-L58) in the source code.
+
+## Why fastapi-ipware?
+
+`python-ipware` expects WSGI-style headers (`HTTP_X_FORWARDED_FOR`), but FastAPI uses natural header names (`X-Forwarded-For`). This wrapper handles the conversion automatically so you don't have to.
+
+## Contributing
+
+Contributions welcome! This is a thin wrapper around python-ipware, so most IP detection logic lives there.
+
+## License
+
+[MIT License](LICENSE.md)
+
+## Credits
+
+Built on top of [python-ipware](https://github.com/un33k/python-ipware) by un33k.

fastapi_ipware-0.1.0/fastapi_ipware/__init__.py

@@ -0,0 +1,110 @@
+import ipaddress
+
+from python_ipware.python_ipware import IpWare  # type: ignore[import-not-found]
+from starlette.requests import Request
+
+
+class FastAPIIpWare(IpWare):
+    """
+    A FastAPI/Starlette-native wrapper around python-ipware that eliminates
+    the need for WSGI-style header conversion at request time.
+
+    This class accepts natural header names (e.g., "X-Forwarded-For") and
+    handles the conversion to ipware's expected format internally.
+
+    Example:
+        >>> from fastapi_ipware import FastAPIIpWare
+        >>> ipware = FastAPIIpWare()
+        >>> ip, trusted = ipware.get_client_ip_from_request(request)
+
+        >>> # With custom precedence
+        >>> ipware = FastAPIIpWare(
+        ...     precedence=("CF-Connecting-IP", "X-Forwarded-For"),
+        ...     proxy_count=1
+        ... )
+    """
+
+    def __init__(
+        self,
+        precedence: tuple[str, ...] | None = None,
+        leftmost: bool = True,
+        proxy_count: int | None = None,
+        proxy_list: list[str] | None = None,
+    ):
+        """
+        Initialize FastAPIIpWare with optional configuration.
+
+        Args:
+            precedence: Tuple of header names to check in order. Uses natural header
+                       names with dashes (e.g., "X-Forwarded-For", "X-Real-IP").
+                       If None, uses FastAPI-optimized defaults.
+            leftmost: If True, use leftmost IP in comma-separated list (standard).
+                     If False, use rightmost IP (rare legacy configurations).
+            proxy_count: Expected number of proxies between client and server.
+                        Used to validate and extract the correct client IP.
+            proxy_list: List of trusted proxy IP prefixes (e.g., ["10.1.", "10.2.3"]).
+        """
+        # FastAPI-native precedence using actual header names with dashes
+        if precedence is None:
+            precedence = (
+                "X-Forwarded-For",  # Most common, used by AWS ELB, nginx, etc.
+                "X-Real-IP",  # NGINX
+                "CF-Connecting-IP",  # Cloudflare
+                "True-Client-IP",  # Cloudflare Enterprise
+                "Fastly-Client-IP",  # Fastly, Firebase
+                "X-Client-IP",  # Microsoft Azure
+                "X-Cluster-Client-IP",  # Rackspace Cloud Load Balancers
+                "Forwarded-For",  # RFC 7239
+                "Forwarded",  # RFC 7239
+                "Client-IP",  # Akamai, Cloudflare
+            )
+
+        # Store FastAPI-style precedence for reference
+        self._fastapi_precedence = precedence
+
+        # Convert user-friendly header names (with dashes) to WSGI format once
+        # This happens only at initialization, not on every request
+        wsgi_precedence = tuple(
+            f"HTTP_{header.upper().replace('-', '_')}" for header in precedence
+        )
+
+        # Initialize parent class with WSGI-style headers
+        super().__init__(wsgi_precedence, leftmost, proxy_count, proxy_list)
+
+    def get_client_ip_from_request(
+        self, request: Request, strict: bool = False
+    ) -> tuple[ipaddress.IPv4Address | ipaddress.IPv6Address | None, bool]:
+        """
+        Get client IP address from a FastAPI/Starlette Request object.
+
+        This is the main method you should use with FastAPI/Starlette applications.
+        It handles the header conversion automatically.
+
+        Args:
+            request: FastAPI/Starlette Request object
+            strict: If True, enforce exact proxy count/list match.
+                   If False, allow more proxies than specified.
+
+        Returns:
+            Tuple of (ip_address, trusted_route) where:
+                - ip_address: IPv4Address or IPv6Address object (or None if not found)
+                - trusted_route: True if request came through trusted proxies, False otherwise
+
+        Example:
+            >>> ip, trusted = ipware.get_client_ip_from_request(request)
+            >>> if ip:
+            ...     print(f"Client IP: {ip}")
+            ...     print(f"Is global: {ip.is_global}")
+            ...     print(f"Is private: {ip.is_private}")
+        """
+        # Convert Starlette headers to WSGI-style dict that parent class expects
+        # This happens once per request
+        meta = {
+            f"HTTP_{name.upper().replace('-', '_')}": value
+            for name, value in request.headers.items()
+        }
+
+        return self.get_client_ip(meta, strict=strict)
+
+
+__all__ = ["FastAPIIpWare"]

fastapi_ipware-0.1.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "fastapi-ipware"
+version = "0.1.0"
+description = "FastAPI/Starlette-native wrapper for python-ipware to get client IP addresses"
+keywords = ["fastapi", "starlette", "ipware", "ip-address", "client-ip", "proxy", "x-forwarded-for"]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "python-ipware>=3.0.0",
+    "starlette>=0.49.1",
+]
+authors = [{ name = "Michael Bianco", email = "mike@mikebian.co" }]
+urls = { "Repository" = "https://github.com/iloveitaly/fastapi-ipware" }
+
+# additional packaging information: https://packaging.python.org/en/latest/specifications/core-metadata/#license
+
+[build-system]
+requires = ["uv_build>=0.8.11,<0.9.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+# avoids the src/ directory structure
+module-root = ""
+
+[dependency-groups]
+dev = ["pytest>=8.3.3","pyright>=1.1.380","ruff>=0.8.0"]
+
+[tool.pyright]
+exclude = ["example.py", ".venv", "**/__pycache__"]
+