fastapi-ipware 0.1.0__tar.gz → 0.1.2__tar.gz

{fastapi_ipware-0.1.0 → fastapi_ipware-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: fastapi-ipware
-Version: 0.1.0
+Version: 0.1.2
 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
@@ -15,28 +15,28 @@ Description-Content-Type: text/markdown
 
 A FastAPI/Starlette-native wrapper for [python-ipware](https://github.com/un33k/python-ipware) that eliminates the need for WSGI-style header conversion.
 
+`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.
+
+Also, 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. This is different from the
+default ordering ipware which deprioritizes platform-specific headers, which is often the wrong ordering if you are using something like CloudFlare.
+
 ## 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
 
+[Take a look at this example usage.](https://github.com/iloveitaly/structlog-config/blob/1e32f7afd206485b1356b322596cc19cb0bef8ba/structlog_config/fastapi_access_logger.py#L57-L72)
+
 ```python
 from fastapi import FastAPI, Request
 from fastapi_ipware import FastAPIIpWare
@@ -137,43 +137,6 @@ ipware = FastAPIIpWare(
 )
 ```
 
-## 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:
@@ -189,26 +152,16 @@ if ip:
 ```
 
 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.
+- Built on top of [python-ipware](https://github.com/un33k/python-ipware) by un33k.
+- https://github.com/long2ice/fastapi-limiter/blob/8d179c058fa2aaf98f3450c9026a7300ae2b3bdd/fastapi_limiter/__init__.py#L11

{fastapi_ipware-0.1.0 → fastapi_ipware-0.1.2}/README.md

@@ -2,28 +2,28 @@
 
 A FastAPI/Starlette-native wrapper for [python-ipware](https://github.com/un33k/python-ipware) that eliminates the need for WSGI-style header conversion.
 
+`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.
+
+Also, 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. This is different from the
+default ordering ipware which deprioritizes platform-specific headers, which is often the wrong ordering if you are using something like CloudFlare.
+
 ## 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
 
+[Take a look at this example usage.](https://github.com/iloveitaly/structlog-config/blob/1e32f7afd206485b1356b322596cc19cb0bef8ba/structlog_config/fastapi_access_logger.py#L57-L72)
+
 ```python
 from fastapi import FastAPI, Request
 from fastapi_ipware import FastAPIIpWare
@@ -124,43 +124,6 @@ ipware = FastAPIIpWare(
 )
 ```
 
-## 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:
@@ -176,26 +139,16 @@ if ip:
 ```
 
 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.
+- Built on top of [python-ipware](https://github.com/un33k/python-ipware) by un33k.
+- https://github.com/long2ice/fastapi-limiter/blob/8d179c058fa2aaf98f3450c9026a7300ae2b3bdd/fastapi_limiter/__init__.py#L11

{fastapi_ipware-0.1.0 → fastapi_ipware-0.1.2}/fastapi_ipware/__init__.py

@@ -44,28 +44,46 @@ class FastAPIIpWare(IpWare):
                         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
+        # Header precedence order: Provider-specific headers before generic ones
+        #
+        # We prioritize provider-specific headers (CF-Connecting-IP, True-Client-IP, etc.)
+        # over generic headers (X-Forwarded-For, X-Real-IP) because:
+        #   1. Provider headers are set by trusted CDN/proxy infrastructure
+        #   2. They cannot be spoofed by clients
+        #   3. They represent the most reliable source of client IP information
+        #
+        # Generic headers like X-Forwarded-For can be set by anyone and are easier
+        # to manipulate, so they should only be used as fallbacks.
         if precedence is None:
             precedence = (
-                "X-Forwarded-For",  # Most common, used by AWS ELB, nginx, etc.
-                "X-Real-IP",  # NGINX
+                # Provider-specific headers (highest reliability)
                 "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
+                # Generic headers (fallback)
+                "X-Forwarded-For",  # Generic, used by AWS ELB, nginx, etc.
+                "X-Real-IP",  # NGINX
+                # NOTE: Upstream python-ipware treats Forwarded headers as plain IP lists.
+                # RFC 7239 `Forwarded` parameters (for=) are not parsed.
+                "Forwarded-For",  # RFC 7239 (plain IP list only)
+                "Forwarded",  # RFC 7239 (plain IP list only)
                 "Client-IP",  # Akamai, Cloudflare
+                "REMOTE_ADDR",  # Direct connection fallback
             )
 
         # 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
+        # Convert user-friendly header names (with dashes) to WSGI format once.
+        # REMOTE_ADDR is a WSGI/ASGI convention, not an HTTP header, so it must
+        # not be prefixed with HTTP_.
         wsgi_precedence = tuple(
-            f"HTTP_{header.upper().replace('-', '_')}" for header in precedence
+            "REMOTE_ADDR"
+            if header == "REMOTE_ADDR"
+            else f"HTTP_{header.upper().replace('-', '_')}"
+            for header in precedence
         )
 
         # Initialize parent class with WSGI-style headers
@@ -104,6 +122,11 @@ class FastAPIIpWare(IpWare):
             for name, value in request.headers.items()
         }
 
+        if request.client:
+            # NOTE: python-ipware falls back to REMOTE_ADDR when no headers match.
+            # Map Starlette's connection info to that expected key.
+            meta["REMOTE_ADDR"] = request.client.host
+
         return self.get_client_ip(meta, strict=strict)
 
 

{fastapi_ipware-0.1.0 → fastapi_ipware-0.1.2}/pyproject.toml

@@ -1,21 +1,26 @@
 [project]
 name = "fastapi-ipware"
-version = "0.1.0"
+version = "0.1.2"
 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"]
+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",
-]
+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"]
+requires = ["uv_build>=0.9.0,<0.10.0"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -23,8 +28,16 @@ build-backend = "uv_build"
 module-root = ""
 
 [dependency-groups]
-dev = ["pytest>=8.3.3","pyright>=1.1.380","ruff>=0.8.0"]
+dev = [
+    "pytest>=8.3.3",
+    "pyright[nodejs]>=1.1.380",
+    "ruff>=0.8.0",
+    "fastapi>=0.128.0",
+    "httpx>=0.28.1",
+]
 
 [tool.pyright]
-exclude = ["example.py", ".venv", "**/__pycache__"]
+exclude = ["examples/", "playground/", "tmp/", ".venv/", "tests/"]
 
+[tool.ruff]
+extend-exclude = ["playground.py", "playground/"]