ipregistry-fastapi 1.0.0__py3-none-any.whl

ipregistry_fastapi/__init__.py

@@ -0,0 +1,74 @@
+"""
+    Official Ipregistry integration for FastAPI.
+
+    Dependency-driven IP geolocation and threat detection for every request,
+    built on the asynchronous Ipregistry Python client.
+
+    Copyright 2026 Ipregistry (https://ipregistry.co).
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+
+from ipregistry import (
+    ApiError as ApiError,
+    ApiResponse as ApiResponse,
+    Carrier as Carrier,
+    ClientError as ClientError,
+    Company as Company,
+    Connection as Connection,
+    Country as Country,
+    Currency as Currency,
+    ErrorCode as ErrorCode,
+    IpInfo as IpInfo,
+    IpregistryError as IpregistryError,
+    IpregistryLookupError as IpregistryLookupError,
+    Location as Location,
+    RequesterIpInfo as RequesterIpInfo,
+    Security as Security,
+    TimeZone as TimeZone,
+    UserAgent as UserAgent,
+)
+
+from .blocking import (
+    Blocker as Blocker,
+    CountryBlocker as CountryBlocker,
+    ThreatBlocker as ThreatBlocker,
+    block_countries as block_countries,
+    block_threats as block_threats,
+)
+from .dependencies import (
+    ClientIpDep as ClientIpDep,
+    IpInfoDep as IpInfoDep,
+    IpregistryDep as IpregistryDep,
+    get_client_ip as get_client_ip,
+    get_ip_info as get_ip_info,
+    get_ipregistry as get_ipregistry,
+)
+from .exceptions import MissingApiKeyError as MissingApiKeyError
+from .guards import is_bot as is_bot, is_eu as is_eu, is_threat as is_threat
+from .ip import (
+    IpExtractor as IpExtractor,
+    IpSource as IpSource,
+    anonymize_ip as anonymize_ip,
+    build_ip_extractor as build_ip_extractor,
+    is_public_ip as is_public_ip,
+)
+from .lifespan import add_ipregistry as add_ipregistry, ipregistry_lifespan as ipregistry_lifespan
+from .middleware import IpregistryMiddleware as IpregistryMiddleware
+from .service import Ipregistry as Ipregistry
+from .settings import (
+    DEFAULT_BASE_URL as DEFAULT_BASE_URL,
+    EU_BASE_URL as EU_BASE_URL,
+    IpregistrySettings as IpregistrySettings,
+)
+from .version import __version__ as __version__

ipregistry_fastapi/blocking.py

@@ -0,0 +1,145 @@
+"""
+    Copyright 2026 Ipregistry (https://ipregistry.co).
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Iterable, Literal, Union
+
+from fastapi import HTTPException
+from fastapi.requests import HTTPConnection
+from ipregistry import IpInfo
+
+from .dependencies import SERVICE_UNAVAILABLE_DETAIL, IpregistryDep
+from .guards import is_threat
+
+_COUNTRY_CODE_PATTERN = re.compile(r"^[A-Za-z]{2}$")
+
+
+class Blocker:
+    """Base for blocking rules, usable both as a FastAPI dependency and as a
+    middleware action."""
+
+    async def __call__(self, connection: HTTPConnection, service: IpregistryDep) -> None:
+        info = await service.for_request(connection)
+        if info is None and not service.settings.fail_open and service.request_error(connection) is not None:
+            raise HTTPException(status_code=503, detail=SERVICE_UNAVAILABLE_DETAIL)
+        self.check(info)
+
+    def check(self, info: IpInfo | None) -> None:
+        """Raise HTTPException when the request must be blocked."""
+        raise NotImplementedError
+
+
+class CountryBlocker(Blocker):
+    def __init__(
+        self,
+        countries: Iterable[str],
+        mode: Literal["block", "allow"],
+        unknown: Literal["allow", "block"],
+        status_code: int,
+        detail: str,
+    ):
+        codes = set()
+        for country in countries:
+            if not isinstance(country, str) or not _COUNTRY_CODE_PATTERN.match(country):
+                raise ValueError(f"Invalid ISO 3166-1 alpha-2 country code: {country!r}")
+            codes.add(country.upper())
+        if not codes:
+            raise ValueError("At least one country code is required")
+        if mode not in ("block", "allow"):
+            raise ValueError(f"Invalid mode {mode!r}: expected 'block' or 'allow'")
+        if unknown not in ("allow", "block"):
+            raise ValueError(f"Invalid unknown policy {unknown!r}: expected 'allow' or 'block'")
+        self.countries = frozenset(codes)
+        self.mode = mode
+        self.unknown = unknown
+        self.status_code = status_code
+        self.detail = detail
+
+    def check(self, info: IpInfo | None) -> None:
+        location = info.location if info is not None else None
+        country = location.country if location is not None else None
+        code = country.code if country is not None else None
+        if code is None:
+            if self.unknown == "block":
+                raise HTTPException(status_code=self.status_code, detail=self.detail)
+            return
+        blocked = code in self.countries if self.mode == "block" else code not in self.countries
+        if blocked:
+            raise HTTPException(status_code=self.status_code, detail=self.detail)
+
+
+def block_countries(
+    *countries: Union[str, Iterable[str]],
+    mode: Literal["block", "allow"] = "block",
+    unknown: Literal["allow", "block"] = "allow",
+    status_code: int = 451,
+    detail: str = "Access restricted in your region.",
+) -> CountryBlocker:
+    """Block (or, with mode='allow', restrict to) visitors from the given
+    ISO 3166-1 alpha-2 countries.
+
+    Use as a route dependency (dependencies=[Depends(block_countries("XX"))])
+    or as a middleware action. Requests whose country cannot be determined are
+    allowed unless unknown='block'. Responds with 451 Unavailable For Legal
+    Reasons by default. Country codes are validated eagerly, at declaration time.
+    """
+    if len(countries) == 1 and not isinstance(countries[0], str):
+        countries = tuple(countries[0])
+    return CountryBlocker(countries, mode, unknown, status_code, detail)
+
+
+class ThreatBlocker(Blocker):
+    def __init__(self, signals: dict[str, bool], status_code: int, detail: str):
+        self.signals = signals
+        self.status_code = status_code
+        self.detail = detail
+
+    def check(self, info: IpInfo | None) -> None:
+        if is_threat(info, **self.signals):
+            raise HTTPException(status_code=self.status_code, detail=self.detail)
+
+
+def block_threats(
+    *,
+    proxy: bool = False,
+    tor: bool = False,
+    vpn: bool = False,
+    relay: bool = False,
+    anonymous: bool = False,
+    cloud_provider: bool = False,
+    bogon: bool = False,
+    status_code: int = 403,
+    detail: str = "Access denied.",
+) -> ThreatBlocker:
+    """Block visitors flagged as threats by Ipregistry.
+
+    Known threats, attackers and abusers are always blocked. Anonymization and
+    infrastructure signals (proxy, tor, vpn, relay, anonymous, cloud_provider,
+    bogon) are opt-in. Requests without security data are allowed (fail open).
+    Use as a route dependency or as a middleware action.
+    """
+    signals = {
+        "proxy": proxy,
+        "tor": tor,
+        "vpn": vpn,
+        "relay": relay,
+        "anonymous": anonymous,
+        "cloud_provider": cloud_provider,
+        "bogon": bogon,
+    }
+    return ThreatBlocker(signals, status_code, detail)

ipregistry_fastapi/dependencies.py

@@ -0,0 +1,72 @@
+"""
+    Copyright 2026 Ipregistry (https://ipregistry.co).
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Optional
+
+from fastapi import Depends, HTTPException
+from fastapi.requests import HTTPConnection
+from ipregistry import IpInfo
+
+from .service import Ipregistry
+
+SERVICE_UNAVAILABLE_DETAIL = "IP intelligence is temporarily unavailable."
+
+
+async def get_ipregistry(connection: HTTPConnection) -> Ipregistry:
+    """Provide the application's Ipregistry service.
+
+    Uses the service attached with add_ipregistry; otherwise lazily creates one
+    from the environment and stores it on the application state.
+    """
+    service = getattr(connection.app.state, "ipregistry", None)
+    if service is None:
+        service = Ipregistry()
+        connection.app.state.ipregistry = service
+    return service
+
+
+IpregistryDep = Annotated[Ipregistry, Depends(get_ipregistry)]
+"""The Ipregistry service, for explicit lookups and access to the raw client."""
+
+
+async def get_ip_info(connection: HTTPConnection, service: IpregistryDep) -> Optional[IpInfo]:
+    """Provide IP intelligence for the request's client, in both HTTP and
+    WebSocket endpoints.
+
+    A single lookup is performed per request and shared by every consumer.
+    Returns None when no public client IP is available or, with fail_open
+    enabled (the default), when the lookup fails. With fail_open disabled a
+    lookup failure responds with 503.
+    """
+    info = await service.for_request(connection)
+    if info is None and not service.settings.fail_open and service.request_error(connection) is not None:
+        raise HTTPException(status_code=503, detail=SERVICE_UNAVAILABLE_DETAIL)
+    return info
+
+
+IpInfoDep = Annotated[Optional[IpInfo], Depends(get_ip_info)]
+"""IP intelligence for the request's client, or None when unavailable."""
+
+
+async def get_client_ip(connection: HTTPConnection, service: IpregistryDep) -> Optional[str]:
+    """Provide the client IP resolved by the configured IP source, or None."""
+    return service.client_ip(connection)
+
+
+ClientIpDep = Annotated[Optional[str], Depends(get_client_ip)]
+"""The resolved public client IP address, or None."""

ipregistry_fastapi/exceptions.py

@@ -0,0 +1,32 @@
+"""
+    Copyright 2026 Ipregistry (https://ipregistry.co).
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+
+from ipregistry import IpregistryError
+
+
+class MissingApiKeyError(IpregistryError):
+    """Raised when an Ipregistry client is built without an API key.
+
+    Set the IPREGISTRY_API_KEY environment variable or pass
+    IpregistrySettings(api_key=...) explicitly.
+    """
+
+    def __init__(self, message: str | None = None):
+        super().__init__(
+            message
+            or "No Ipregistry API key configured. Set the IPREGISTRY_API_KEY environment "
+            "variable or pass IpregistrySettings(api_key=...) explicitly."
+        )

ipregistry_fastapi/guards.py

@@ -0,0 +1,81 @@
+"""
+    Copyright 2026 Ipregistry (https://ipregistry.co).
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+
+from __future__ import annotations
+
+from typing import Union
+
+from fastapi.requests import HTTPConnection
+from ipregistry import IpInfo, UserAgents
+
+
+def is_eu(info: IpInfo | None, *, assume_eu: bool = False) -> bool:
+    """Return True when the IP is located in the European Union.
+
+    Useful for GDPR consent flows. When the EU membership is unknown (no data),
+    returns assume_eu, so pass assume_eu=True to err on the side of showing a
+    consent banner.
+    """
+    in_eu = info.location.in_eu if info is not None and info.location is not None else None
+    return assume_eu if in_eu is None else in_eu
+
+
+def is_threat(
+    info: IpInfo | None,
+    *,
+    proxy: bool = False,
+    tor: bool = False,
+    vpn: bool = False,
+    relay: bool = False,
+    anonymous: bool = False,
+    cloud_provider: bool = False,
+    bogon: bool = False,
+) -> bool:
+    """Return True when the IP is a known threat.
+
+    Known threats, attackers and abusers are always flagged. Anonymization
+    signals (proxy, tor, vpn, relay, anonymous) and infrastructure signals
+    (cloud_provider, bogon) are opt-in since they are not inherently malicious.
+    Returns False when no security data is available (fail open).
+    """
+    security = info.security if info is not None else None
+    if security is None:
+        return False
+    signals = [security.is_threat, security.is_attacker, security.is_abuser]
+    if proxy:
+        signals.append(security.is_proxy)
+    if tor:
+        signals.extend((security.is_tor, security.is_tor_exit))
+    if vpn:
+        signals.append(security.is_vpn)
+    if relay:
+        signals.append(security.is_relay)
+    if anonymous:
+        signals.append(security.is_anonymous)
+    if cloud_provider:
+        signals.append(security.is_cloud_provider)
+    if bogon:
+        signals.append(security.is_bogon)
+    return any(bool(signal) for signal in signals)
+
+
+def is_bot(subject: Union[HTTPConnection, str, None]) -> bool:
+    """Return True when the request or User-Agent string looks like a bot or
+    crawler. Heuristic string check; no API call and no credit consumed."""
+    if subject is None:
+        return False
+    header = subject if isinstance(subject, str) else subject.headers.get("user-agent", "")
+    return bool(header) and UserAgents.is_bot(header)

ipregistry_fastapi/ip.py

@@ -0,0 +1,153 @@
+"""
+    Copyright 2026 Ipregistry (https://ipregistry.co).
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+from typing import Callable, Optional, Union
+
+from fastapi.requests import HTTPConnection
+
+IpExtractor = Callable[[HTTPConnection], Optional[str]]
+"""A callable that extracts the client IP address from an HTTP or WebSocket connection, or None."""
+
+IpSource = Union[str, IpExtractor]
+"""An IP source: 'client', a trusted-proxy preset name, 'header:<name>' or a callable."""
+
+PRESET_HEADERS: dict[str, tuple[str, ...]] = {
+    "auto": ("x-real-ip", "x-forwarded-for"),
+    "cloudflare": ("cf-connecting-ip",),
+    "nginx": ("x-real-ip", "x-forwarded-for"),
+    "forwarded-for": ("x-forwarded-for",),
+}
+"""Headers consulted, in order, for each trusted-proxy preset."""
+
+
+def sanitize_ip(value: str | None) -> str | None:
+    """Normalize a raw header or address value to a bare IP string.
+
+    Strips whitespace, IPv6 brackets (with an optional port, e.g. '[::1]:8080'),
+    an IPv4 port suffix (e.g. '1.2.3.4:443') and IPv6 zone identifiers ('%eth0').
+    Returns None when nothing is left.
+    """
+    if value is None:
+        return None
+    value = value.strip()
+    if value.startswith("["):
+        end = value.find("]")
+        if end == -1:
+            return None
+        value = value[1:end]
+    elif value.count(":") == 1 and "." in value:
+        value = value.split(":", 1)[0]
+    zone = value.find("%")
+    if zone != -1:
+        value = value[:zone]
+    return value or None
+
+
+def is_valid_ip(value: str) -> bool:
+    """Return True when the value is a valid IPv4 or IPv6 address."""
+    try:
+        ipaddress.ip_address(value)
+    except ValueError:
+        return False
+    return True
+
+
+def is_public_ip(value: str) -> bool:
+    """Return True when the value is a valid, publicly routable IP address.
+
+    Private, loopback, link-local, carrier-grade NAT and other reserved ranges
+    return False: the Ipregistry API rejects them with RESERVED_IP_ADDRESS, so
+    lookups for such addresses are skipped.
+    """
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError:
+        return False
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped is not None:
+        address = address.ipv4_mapped
+    return address.is_global and not address.is_multicast
+
+
+def anonymize_ip(value: str) -> str:
+    """Mask an IP address for log output; this library never logs full client IPs."""
+    try:
+        address = ipaddress.ip_address(value)
+    except ValueError:
+        return "<invalid>"
+    if isinstance(address, ipaddress.IPv4Address):
+        octets = str(address).split(".")
+        return ".".join(octets[:3]) + ".x"
+    groups = address.exploded.split(":")
+    return ":".join(groups[:3]) + "::x"
+
+
+def build_ip_extractor(source: IpSource = "client") -> IpExtractor:
+    """Build an IP extractor from an IP source specification.
+
+    Accepts 'client' (the ASGI client address), a trusted-proxy preset name
+    ('auto', 'cloudflare', 'nginx', 'forwarded-for'), 'header:<name>' for a
+    custom header, or a callable taking a connection and returning an IP or None.
+
+    Only configure headers set by a proxy you control: client-supplied headers
+    are trivially spoofable.
+    """
+    if callable(source):
+        return source
+
+    normalized = source.strip().lower()
+    if normalized == "client":
+        return _extract_from_client
+
+    if normalized.startswith("header:"):
+        header = normalized.split(":", 1)[1].strip()
+        if not header:
+            raise ValueError("Invalid IP source: 'header:' requires a header name, e.g. 'header:x-client-ip'")
+        headers: tuple[str, ...] = (header,)
+    elif normalized in PRESET_HEADERS:
+        headers = PRESET_HEADERS[normalized]
+    else:
+        presets = ", ".join(sorted(PRESET_HEADERS))
+        raise ValueError(
+            f"Unknown IP source {source!r}: expected 'client', a preset ({presets}), "
+            "'header:<name>' or a callable"
+        )
+
+    def extract(connection: HTTPConnection) -> str | None:
+        return _extract_from_headers(connection, headers)
+
+    return extract
+
+
+def _extract_from_client(connection: HTTPConnection) -> str | None:
+    client = connection.client
+    if client is None or not client.host:
+        return None
+    ip = sanitize_ip(client.host)
+    return ip if ip is not None and is_valid_ip(ip) else None
+
+
+def _extract_from_headers(connection: HTTPConnection, headers: tuple[str, ...]) -> str | None:
+    for name in headers:
+        raw = connection.headers.get(name)
+        if not raw:
+            continue
+        ip = sanitize_ip(raw.split(",", 1)[0])
+        if ip is not None and is_valid_ip(ip):
+            return ip
+    return None

ipregistry_fastapi/lifespan.py

@@ -0,0 +1,65 @@
+"""
+    Copyright 2026 Ipregistry (https://ipregistry.co).
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+       https://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is distributed on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+    See the License for the specific language governing permissions and
+    limitations under the License.
+"""
+
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+from fastapi import FastAPI
+from ipregistry import AsyncIpregistryClient
+
+from .ip import IpSource
+from .service import Ipregistry
+from .settings import IpregistrySettings
+
+
+def add_ipregistry(
+    app: FastAPI,
+    settings: IpregistrySettings | None = None,
+    *,
+    client: AsyncIpregistryClient | None = None,
+    ip_extractor: IpSource | None = None,
+    service: Ipregistry | None = None,
+) -> Ipregistry:
+    """Attach an Ipregistry service to the application state.
+
+    The service is picked up by the dependencies (IpInfoDep, IpregistryDep, ...)
+    and the middleware. Pass a pre-built service (e.g. an IpregistryFake in
+    tests) or let one be created from the given settings and environment.
+    """
+    if service is None:
+        service = Ipregistry(settings, client=client, ip_extractor=ip_extractor)
+    app.state.ipregistry = service
+    return service
+
+
+@asynccontextmanager
+async def ipregistry_lifespan(app: FastAPI) -> AsyncIterator[None]:
+    """Application lifespan managing the Ipregistry service lifecycle.
+
+    Use directly (FastAPI(lifespan=ipregistry_lifespan)) or compose it inside
+    your own lifespan with an AsyncExitStack. Creates a service from the
+    environment unless one was already attached with add_ipregistry, and
+    releases its HTTP resources on shutdown.
+    """
+    service = getattr(app.state, "ipregistry", None)
+    if service is None:
+        service = add_ipregistry(app)
+    try:
+        yield
+    finally:
+        await service.aclose()