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

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

@@ -1,16 +1,26 @@
 Metadata-Version: 2.3
 Name: fastapi-ipware
-Version: 0.1.2
+Version: 1.0.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
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: python-ipware>=4.1.0
 Requires-Dist: starlette>=0.49.1
-Requires-Python: >=3.10
+Requires-Python: >=3.12
 Project-URL: Repository, https://github.com/iloveitaly/fastapi-ipware
 Description-Content-Type: text/markdown
 
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/fastapi-ipware)](https://github.com/iloveitaly/fastapi-ipware/releases)
+[![Downloads](https://static.pepy.tech/badge/fastapi-ipware/month)](https://pepy.tech/project/fastapi-ipware)
+![GitHub CI Status](https://github.com/iloveitaly/fastapi-ipware/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
 # 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.
@@ -35,7 +45,36 @@ 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)
+### Using FastAPI Dependency Injection
+
+```python
+from typing import Annotated
+from fastapi import Depends, FastAPI
+from fastapi_ipware import ClientIpResult, FastAPIIpWare
+
+app = FastAPI()
+ipware = FastAPIIpWare()
+
+
+@app.get("/")
+async def get_ip(client: Annotated[ClientIpResult, Depends(ipware)]):
+    # trusted is true only when the request came through the proxies
+    # configured with proxy_count or proxy_list
+    ip, trusted = client
+    return {
+        "ip": str(ip) if ip else None,
+        "trusted": trusted,
+        "is_public": ip.is_global if ip else None,
+    }
+
+
+# Or inject only the IP object or string directly:
+@app.get("/ip-string")
+async def get_ip_string(ip_str: Annotated[str | None, Depends(ipware.get_ip_str)]):
+    return {"ip": ip_str}
+```
+
+### Using Request Directly
 
 ```python
 from fastapi import FastAPI, Request
@@ -44,32 +83,40 @@ 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"}
+    return {"ip": str(ip) if ip else None, "trusted": trusted}
 ```
 
-## Usage
+### Using ASGI Middleware
 
-### Basic Usage
+Automatically extract the client IP onto `request.state` for every request:
 
 ```python
-from fastapi_ipware import FastAPIIpWare
+from fastapi import FastAPI, Request
+from fastapi_ipware import IpWareMiddleware
 
-# Use default configuration (optimized for FastAPI/cloud deployments)
-ipware = FastAPIIpWare()
+app = FastAPI()
+app.add_middleware(IpWareMiddleware)
 
-ip, trusted = ipware.get_client_ip_from_request(request)
+
+@app.get("/")
+async def get_ip(request: Request):
+    return {
+        "ip": request.state.client_ip_str,
+        "trusted": request.state.ip_trusted,
+    }
+```
+
+Pass a configured resolver when you need one. Omit `strict` to use that resolver's `default_strict`; pass `strict=` to override it.
+
+```python
+from fastapi_ipware import FastAPIIpWare, IpWareMiddleware
+
+ipware = FastAPIIpWare(proxy_count=1, default_strict=True)
+app.add_middleware(IpWareMiddleware, ipware=ipware)
 ```
 
 ### Custom Header Precedence
@@ -100,8 +147,13 @@ ipware = FastAPIIpWare(
 Validate that requests pass through the expected number of proxies:
 
 ```python
-# Expect exactly 1 proxy (e.g., AWS ALB)
-ipware = FastAPIIpWare(proxy_count=1)
+# Expect exactly 1 proxy (e.g., AWS ALB).
+# proxy_count=N returns the address just left of the N rightmost proxies,
+# instead of the first public address, and rejects a shorter chain.
+# X-Forwarded-For: 203.0.113.10, 10.0.0.1, 10.0.0.2 returns 203.0.113.10
+# with no proxy_count, and 10.0.0.1 with proxy_count=1.
+# default_strict applies to Depends(ipware), dependency(), and IpWareMiddleware.
+ipware = FastAPIIpWare(proxy_count=1, default_strict=True)
 
 # In strict mode, must be exactly 1 proxy
 ip, trusted = ipware.get_client_ip_from_request(request, strict=True)
@@ -112,12 +164,12 @@ ip, trusted = ipware.get_client_ip_from_request(request, strict=False)
 
 ### Trusted Proxy List
 
-Validate that requests pass through specific trusted proxies:
+Validate that requests pass through specific trusted proxies (supports IP prefixes, exact IPs, and CIDR networks):
 
 ```python
-# Trust specific proxy IP prefixes
+# Trust specific proxy IP prefixes or CIDR networks
 ipware = FastAPIIpWare(
-    proxy_list=["10.0.", "10.1."]  # AWS internal IPs
+    proxy_list=["10.0.", "10.1.", "100.64.0.0/10"]  # AWS internal IPs and CGNAT CIDR
 )
 
 ip, trusted = ipware.get_client_ip_from_request(request)
@@ -131,10 +183,19 @@ 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."]
-)
+ipware = FastAPIIpWare(proxy_count=1, proxy_list=["10.0."])
+```
+
+### Algorithm Engine Selection
+
+Choose between python-ipware 4.x engines (`auto` / `modern` / `legacy`):
+
+```python
+# Modern engine (default): enhanced header parsing and RFC 7239 support
+ipware = FastAPIIpWare(algorithm="modern")
+
+# Legacy engine: frozen byte-for-byte v3 behavior
+ipware = FastAPIIpWare(algorithm="legacy")
 ```
 
 ## IP Address Types
@@ -165,3 +226,7 @@ python-ipware automatically prefers:
 
 - 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
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

fastapi_ipware-1.0.0/README.md

@@ -0,0 +1,214 @@
+[![Release Notes](https://img.shields.io/github/release/iloveitaly/fastapi-ipware)](https://github.com/iloveitaly/fastapi-ipware/releases)
+[![Downloads](https://static.pepy.tech/badge/fastapi-ipware/month)](https://pepy.tech/project/fastapi-ipware)
+![GitHub CI Status](https://github.com/iloveitaly/fastapi-ipware/actions/workflows/build_and_publish.yml/badge.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+# 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.
+
+`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
+
+## Installation
+
+```bash
+uv add fastapi-ipware
+```
+
+## Quick Start
+
+### Using FastAPI Dependency Injection
+
+```python
+from typing import Annotated
+from fastapi import Depends, FastAPI
+from fastapi_ipware import ClientIpResult, FastAPIIpWare
+
+app = FastAPI()
+ipware = FastAPIIpWare()
+
+
+@app.get("/")
+async def get_ip(client: Annotated[ClientIpResult, Depends(ipware)]):
+    # trusted is true only when the request came through the proxies
+    # configured with proxy_count or proxy_list
+    ip, trusted = client
+    return {
+        "ip": str(ip) if ip else None,
+        "trusted": trusted,
+        "is_public": ip.is_global if ip else None,
+    }
+
+
+# Or inject only the IP object or string directly:
+@app.get("/ip-string")
+async def get_ip_string(ip_str: Annotated[str | None, Depends(ipware.get_ip_str)]):
+    return {"ip": ip_str}
+```
+
+### Using Request Directly
+
+```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)
+    return {"ip": str(ip) if ip else None, "trusted": trusted}
+```
+
+### Using ASGI Middleware
+
+Automatically extract the client IP onto `request.state` for every request:
+
+```python
+from fastapi import FastAPI, Request
+from fastapi_ipware import IpWareMiddleware
+
+app = FastAPI()
+app.add_middleware(IpWareMiddleware)
+
+
+@app.get("/")
+async def get_ip(request: Request):
+    return {
+        "ip": request.state.client_ip_str,
+        "trusted": request.state.ip_trusted,
+    }
+```
+
+Pass a configured resolver when you need one. Omit `strict` to use that resolver's `default_strict`; pass `strict=` to override it.
+
+```python
+from fastapi_ipware import FastAPIIpWare, IpWareMiddleware
+
+ipware = FastAPIIpWare(proxy_count=1, default_strict=True)
+app.add_middleware(IpWareMiddleware, ipware=ipware)
+```
+
+### 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).
+# proxy_count=N returns the address just left of the N rightmost proxies,
+# instead of the first public address, and rejects a shorter chain.
+# X-Forwarded-For: 203.0.113.10, 10.0.0.1, 10.0.0.2 returns 203.0.113.10
+# with no proxy_count, and 10.0.0.1 with proxy_count=1.
+# default_strict applies to Depends(ipware), dependency(), and IpWareMiddleware.
+ipware = FastAPIIpWare(proxy_count=1, default_strict=True)
+
+# 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 (supports IP prefixes, exact IPs, and CIDR networks):
+
+```python
+# Trust specific proxy IP prefixes or CIDR networks
+ipware = FastAPIIpWare(
+    proxy_list=["10.0.", "10.1.", "100.64.0.0/10"]  # AWS internal IPs and CGNAT CIDR
+)
+
+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."])
+```
+
+### Algorithm Engine Selection
+
+Choose between python-ipware 4.x engines (`auto` / `modern` / `legacy`):
+
+```python
+# Modern engine (default): enhanced header parsing and RFC 7239 support
+ipware = FastAPIIpWare(algorithm="modern")
+
+# Legacy engine: frozen byte-for-byte v3 behavior
+ipware = FastAPIIpWare(algorithm="legacy")
+```
+
+## 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
+
+## License
+
+[MIT License](LICENSE.md)
+
+## Credits
+
+- 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
+
+---
+
+*This project was created from [iloveitaly/python-package-template](https://github.com/iloveitaly/python-package-template)*

fastapi_ipware-1.0.0/fastapi_ipware/__init__.py

@@ -0,0 +1,275 @@
+import ipaddress
+from collections.abc import Callable
+from typing import Literal
+
+from python_ipware import IpWare
+from starlette.requests import HTTPConnection
+from starlette.types import ASGIApp, Receive, Scope, Send
+
+from .version import __version__
+
+Algorithm = Literal["auto", "modern", "legacy"]
+IpAddressType = ipaddress.IPv4Address | ipaddress.IPv6Address
+ClientIpResult = tuple[IpAddressType | None, bool]
+
+DEFAULT_PRECEDENCE: tuple[str, ...] = (
+    # provider-specific headers (highest reliability)
+    # cloudflare
+    "CF-Connecting-IP",
+    # cloudflare enterprise, akamai
+    "True-Client-IP",
+    # fastly, firebase
+    "Fastly-Client-IP",
+    # fly.io
+    "Fly-Client-IP",
+    # microsoft azure
+    "X-Client-IP",
+    # azure front door
+    "X-Azure-ClientIP",
+    # digitalocean app platform
+    "DO-Connecting-IP",
+    # rackspace cloud load balancers
+    "X-Cluster-Client-IP",
+    # google app engine
+    "X-Appengine-User-IP",
+    # envoy / istio
+    "X-Envoy-External-Address",
+    # generic headers (fallback)
+    # generic, used by aws elb, nginx, etc
+    "X-Forwarded-For",
+    # nginx
+    "X-Real-IP",
+    # plain ip list variant
+    "Forwarded-For",
+    # rfc 7239 (for=...;proto=...)
+    "Forwarded",
+    # akamai, cloudflare fallback
+    "Client-IP",
+    # direct connection fallback
+    "REMOTE_ADDR",
+)
+
+
+def _expand_header_variants(header: str) -> tuple[str, ...]:
+    "Expand a single header name into its natural and WSGI variants"
+    if header == "REMOTE_ADDR":
+        return ("REMOTE_ADDR",)
+
+    if header.startswith("HTTP_"):
+        return (header, header[5:].replace("_", "-"))
+
+    return (header, f"HTTP_{header.upper().replace('-', '_')}")
+
+
+def _expand_header_precedence(precedence: tuple[str, ...]) -> tuple[str, ...]:
+    "Expand header precedence tuple to include natural and WSGI formats"
+    expanded: list[str] = []
+    for header in precedence:
+        for variant in _expand_header_variants(header):
+            if variant in expanded:
+                continue
+
+            expanded.append(variant)
+
+    return tuple(expanded)
+
+
+def _build_request_meta(request: HTTPConnection) -> dict[str, str]:
+    "Build a metadata dictionary containing WSGI and natural headers from request"
+    # populate both wsgi-style headers and original starlette headers
+    meta = {
+        f"HTTP_{name.upper().replace('-', '_')}": value
+        for name, value in request.headers.items()
+    }
+    for name, value in request.headers.items():
+        meta[name] = value
+
+    if request.client:
+        # map starlette's connection info to remote_addr fallback
+        meta["REMOTE_ADDR"] = request.client.host
+
+    return meta
+
+
+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)
+
+        >>> # Direct FastAPI route dependency
+        >>> @app.get("/")
+        ... def endpoint(client: ClientIpResult = Depends(ipware)):
+        ...     ip, trusted = client
+    """
+
+    def __init__(
+        self,
+        precedence: tuple[str, ...] | None = None,
+        leftmost: bool = True,
+        proxy_count: int | None = None,
+        proxy_list: list[str] | None = None,
+        algorithm: Algorithm = "auto",
+        default_strict: bool = False,
+    ):
+        """
+        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, complete IPs, or CIDR networks
+                       (e.g., ["10.1.", "198.84.193.157", "100.64.0.0/10"]).
+            algorithm: Algorithm engine to use: "auto" (default, uses modern),
+                      "modern" (v4 enhanced engine), or "legacy" (frozen v3 engine).
+            default_strict: Used whenever strict is omitted: Depends(self),
+                           dependency() with no argument, IpWareMiddleware, and
+                           get_client_ip_from_request.
+        """
+        if precedence is None:
+            precedence = DEFAULT_PRECEDENCE
+
+        # store fastapi-style precedence for reference
+        self._fastapi_precedence = precedence
+        self.default_strict = default_strict
+
+        # expand precedence to support both natural and wsgi formats
+        expanded_precedence = _expand_header_precedence(precedence)
+
+        super().__init__(
+            expanded_precedence,
+            leftmost=leftmost,
+            proxy_count=proxy_count,
+            proxy_list=proxy_list,
+            algorithm=algorithm,
+        )
+
+    @property
+    def precedence(self) -> tuple[str, ...]:
+        "Header precedence tuple from the active engine"
+        return getattr(self.engine, "precedence", ())
+
+    @property
+    def leftmost(self) -> bool:
+        "Leftmost setting from the active engine"
+        return getattr(self.engine, "leftmost", True)
+
+    @property
+    def proxy_count(self) -> int | None:
+        "Proxy count setting from the active engine"
+        return getattr(self.engine, "proxy_count", None)
+
+    @property
+    def proxy_list(self) -> list[str]:
+        "Proxy list setting from the active engine"
+        return getattr(self.engine, "proxy_list", [])
+
+    def __call__(self, request: HTTPConnection) -> ClientIpResult:
+        "FastAPI route dependency injection entrypoint"
+        return self.get_client_ip_from_request(request, strict=self.default_strict)
+
+    def dependency(
+        self, strict: bool | None = None
+    ) -> Callable[[HTTPConnection], ClientIpResult]:
+        "Return a FastAPI dependency. An omitted strict flag uses default_strict"
+
+        def _dep(request: HTTPConnection) -> ClientIpResult:
+            return self.get_client_ip_from_request(request, strict=strict)
+
+        return _dep
+
+    def get_ip(self, request: HTTPConnection) -> IpAddressType | None:
+        "Return only the client IP address (or None if unresolvable)"
+        ip, _ = self.get_client_ip_from_request(request, strict=self.default_strict)
+
+        return ip
+
+    def get_ip_str(self, request: HTTPConnection) -> str | None:
+        "Return the client IP address as a string (or None if unresolvable)"
+        ip = self.get_ip(request)
+        if ip is None:
+            return None
+
+        return str(ip)
+
+    def get_client_ip_from_request(
+        self, request: HTTPConnection, strict: bool | None = None
+    ) -> ClientIpResult:
+        """
+        Get client IP address from a FastAPI/Starlette Request or WebSocket connection.
+
+        Args:
+            request: FastAPI/Starlette Request or HTTPConnection object
+            strict: If True, enforce exact proxy count/list match.
+                   If False, allow more proxies than specified.
+                   If None, use self.default_strict.
+
+        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
+        """
+        effective_strict = self.default_strict if strict is None else strict
+        meta = _build_request_meta(request)
+
+        return self.get_client_ip(meta, strict=effective_strict)
+
+
+class IpWareMiddleware:
+    """
+    ASGI middleware that resolves the client IP address and attaches it to request state:
+      - `request.state.client_ip`: IPv4Address | IPv6Address | None
+      - `request.state.ip_trusted`: bool
+      - `request.state.client_ip_str`: str | None
+
+    Pass `ipware` to use a configured resolver. `strict` overrides that
+    resolver's `default_strict`; omit it to use `default_strict`.
+    """
+
+    def __init__(
+        self,
+        app: ASGIApp,
+        ipware: FastAPIIpWare | None = None,
+        strict: bool | None = None,
+    ) -> None:
+        self.app = app
+        self.ipware = ipware if ipware is not None else FastAPIIpWare()
+        self.strict = strict
+
+    async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None:
+        if scope["type"] not in ("http", "websocket"):
+            await self.app(scope, receive, send)
+            return
+
+        conn = HTTPConnection(scope)
+        ip, trusted = self.ipware.get_client_ip_from_request(conn, strict=self.strict)
+
+        scope.setdefault("state", {})
+        scope["state"]["client_ip"] = ip
+        scope["state"]["ip_trusted"] = trusted
+        scope["state"]["client_ip_str"] = str(ip) if ip is not None else None
+
+        await self.app(scope, receive, send)
+
+
+__all__ = [
+    "DEFAULT_PRECEDENCE",
+    "Algorithm",
+    "ClientIpResult",
+    "FastAPIIpWare",
+    "IpAddressType",
+    "IpWareMiddleware",
+    "__version__",
+]

fastapi_ipware-1.0.0/fastapi_ipware/version.py

@@ -0,0 +1,35 @@
+"Version handling for fastapi-ipware"
+
+import importlib.metadata
+from pathlib import Path
+
+
+def is_local_source_checkout() -> bool:
+    "Check if the code is running from a local source checkout"
+    package_dir = Path(__file__).resolve().parent
+
+    # since this is a flat layout (module-root = ""), repo root is the parent of the package dir
+    repo_root = package_dir.parent
+
+    return (repo_root / ".git").exists() and (repo_root / "pyproject.toml").exists()
+
+
+def get_version() -> str:
+    "Get the version string, appending .dev if running from source"
+    try:
+        # try to get the version of the installed package
+        version = importlib.metadata.version("fastapi-ipware")
+    except importlib.metadata.PackageNotFoundError:
+        # fallback for local development if not installed
+        version = "1.0.0"
+
+    if not is_local_source_checkout():
+        return version
+
+    if version.endswith(".dev"):
+        return version
+
+    return f"{version}.dev"
+
+
+__version__ = get_version()

fastapi_ipware-1.0.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "fastapi-ipware"
+version = "1.0.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.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = [
+    "python-ipware>=4.1.0",
+    "starlette>=0.49.1",
+]
+
+[[project.authors]]
+name = "Michael Bianco"
+email = "mike@mikebian.co"
+
+[project.urls]
+Repository = "https://github.com/iloveitaly/fastapi-ipware"
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.14"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = ""
+
+[tool.pyright]
+exclude = [
+    "examples/",
+    "playground/",
+    "tmp/",
+    ".venv/",
+    "tests/",
+]
+
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=term-missing --cov-report=html:tmp/htmlcov"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["fastapi_ipware"]
+
+[tool.coverage.report]
+fail_under = 50
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.4",
+    "pyright[nodejs]>=1.1.408",
+    "ruff>=0.15.0",
+    "coverage>=7.13.4",
+    "pytest-cov>=7.0.0",
+    "covdefaults>=2.3.0",
+    "beautiful-traceback>=1.0.2",
+    "fastapi>=0.128.0",
+    "httpx>=0.28.1",
+]

fastapi_ipware-0.1.2/pyproject.toml → fastapi_ipware-1.0.0/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "fastapi-ipware"
-version = "0.1.2"
+version = "1.0.0"
 description = "FastAPI/Starlette-native wrapper for python-ipware to get client IP addresses"
 keywords = [
     "fastapi",
@@ -12,15 +12,22 @@ keywords = [
     "x-forwarded-for",
 ]
 readme = "README.md"
-requires-python = ">=3.10"
-dependencies = ["python-ipware>=3.0.0", "starlette>=0.49.1"]
+requires-python = ">=3.12"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+dependencies = ["python-ipware>=4.1.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.9.0,<0.10.0"]
+requires = ["uv_build>=0.11.0,<0.14"]
 build-backend = "uv_build"
 
 [tool.uv.build-backend]
@@ -29,9 +36,13 @@ module-root = ""
 
 [dependency-groups]
 dev = [
-    "pytest>=8.3.3",
-    "pyright[nodejs]>=1.1.380",
-    "ruff>=0.8.0",
+    "pytest>=8.3.4",
+    "pyright[nodejs]>=1.1.408",
+    "ruff>=0.15.0",
+    "coverage>=7.13.4",
+    "pytest-cov>=7.0.0",
+    "covdefaults>=2.3.0",
+    "beautiful-traceback>=1.0.2",
     "fastapi>=0.128.0",
     "httpx>=0.28.1",
 ]
@@ -39,5 +50,12 @@ dev = [
 [tool.pyright]
 exclude = ["examples/", "playground/", "tmp/", ".venv/", "tests/"]
 
-[tool.ruff]
-extend-exclude = ["playground.py", "playground/"]
+[tool.pytest.ini_options]
+addopts = "--cov --cov-report=term-missing --cov-report=html:tmp/htmlcov"
+
+[tool.coverage.run]
+plugins = ["covdefaults"]
+source = ["fastapi_ipware"]
+
+[tool.coverage.report]
+fail_under = 50

fastapi_ipware-0.1.2/README.md

@@ -1,154 +0,0 @@
-# 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.
-
-`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
-
-## Installation
-
-```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
-
-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."]
-)
-```
-
-## 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
-
-## License
-
-[MIT License](LICENSE.md)
-
-## Credits
-
-- 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.2/fastapi_ipware/__init__.py

@@ -1,133 +0,0 @@
-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"]).
-        """
-        # 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 = (
-                # 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
-                # 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.
-        # REMOTE_ADDR is a WSGI/ASGI convention, not an HTTP header, so it must
-        # not be prefixed with HTTP_.
-        wsgi_precedence = tuple(
-            "REMOTE_ADDR"
-            if header == "REMOTE_ADDR"
-            else 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()
-        }
-
-        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)
-
-
-__all__ = ["FastAPIIpWare"]