ipregistry-fastapi 1.0.0__py3-none-any.whl

ipregistry_fastapi/middleware.py

@@ -0,0 +1,144 @@
+"""
+    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 Callable, Sequence, Union
+
+from fastapi import HTTPException, Request
+from fastapi.responses import PlainTextResponse
+from ipregistry import UserAgents
+
+from .blocking import Blocker
+from .dependencies import SERVICE_UNAVAILABLE_DETAIL
+from .service import Ipregistry
+from .settings import IpregistrySettings
+
+STATIC_ASSET_SUFFIXES = (
+    ".avif", ".css", ".gif", ".ico", ".jpeg", ".jpg", ".js", ".map", ".mjs",
+    ".otf", ".png", ".svg", ".ttf", ".txt", ".webmanifest", ".webp", ".woff", ".woff2",
+)
+
+
+class IpregistryMiddleware:
+    """Pure ASGI middleware enriching every HTTP request with IP intelligence.
+
+    Performs a single cached lookup per request, stores the result on
+    request.state.ipregistry (shared with the IpInfoDep dependency), and
+    optionally applies blocking actions before the request reaches the router:
+
+        app.add_middleware(
+            IpregistryMiddleware,
+            actions=[block_countries("XX"), block_threats(tor=True)],
+        )
+
+    Prefer route dependencies for per-endpoint rules; use the middleware to
+    enforce app-wide policies or to eagerly enrich every request.
+
+    Parameters:
+    service: the Ipregistry service to use. Defaults to the one attached to
+        the application state, else one built from settings / the environment.
+    settings: settings used when building a service lazily.
+    fields / hostname: per-lookup overrides forwarded to the lookup.
+    actions: blocking rules (block_countries, block_threats, or any Blocker)
+        evaluated in order; the first match returns its error response.
+    fail_closed: when True, respond with 503 if the lookup fails; an int
+        customizes the status code. Defaults to False (fail open).
+    skip_static_assets: skip lookups for common static file extensions.
+    skip_bots: skip lookups when the User-Agent looks like a bot or crawler.
+    skip: custom predicate receiving the request; return True to skip.
+    """
+
+    def __init__(
+        self,
+        app,
+        *,
+        service: Ipregistry | None = None,
+        settings: IpregistrySettings | None = None,
+        fields: str | None = None,
+        hostname: bool | None = None,
+        actions: Sequence[Blocker] = (),
+        fail_closed: Union[bool, int] = False,
+        skip_static_assets: bool = True,
+        skip_bots: bool = False,
+        skip: Callable[[Request], bool] | None = None,
+    ):
+        self.app = app
+        self._service = service
+        self._settings = settings
+        self._fields = fields
+        self._hostname = hostname
+        self._actions = tuple(actions)
+        self._fail_closed = fail_closed
+        self._skip_static_assets = skip_static_assets
+        self._skip_bots = skip_bots
+        self._skip = skip
+
+    async def __call__(self, scope, receive, send) -> None:
+        if scope["type"] != "http":
+            await self.app(scope, receive, send)
+            return
+
+        scope.setdefault("state", {})
+        request = Request(scope, receive)
+
+        if not self._should_skip(request):
+            service = self._resolve_service(scope)
+            info = await service.for_request(request, fields=self._fields, hostname=self._hostname)
+
+            if info is None and self._fail_closed and service.request_error(request) is not None:
+                status_code = 503 if self._fail_closed is True else int(self._fail_closed)
+                response = PlainTextResponse(SERVICE_UNAVAILABLE_DETAIL, status_code=status_code)
+                await response(scope, receive, send)
+                return
+
+            for action in self._actions:
+                try:
+                    action.check(info)
+                except HTTPException as exception:
+                    response = PlainTextResponse(
+                        str(exception.detail),
+                        status_code=exception.status_code,
+                        headers=exception.headers,
+                    )
+                    await response(scope, receive, send)
+                    return
+
+        await self.app(scope, receive, send)
+
+    def _resolve_service(self, scope) -> Ipregistry:
+        if self._service is not None:
+            return self._service
+        app = scope.get("app")
+        if app is not None:
+            existing = getattr(app.state, "ipregistry", None)
+            if existing is not None:
+                self._service = existing
+                return existing
+        service = Ipregistry(self._settings)
+        if app is not None:
+            app.state.ipregistry = service
+        self._service = service
+        return service
+
+    def _should_skip(self, request: Request) -> bool:
+        if self._skip_static_assets and request.url.path.lower().endswith(STATIC_ASSET_SUFFIXES):
+            return True
+        if self._skip_bots:
+            user_agent = request.headers.get("user-agent", "")
+            if user_agent and UserAgents.is_bot(user_agent):
+                return True
+        return self._skip is not None and self._skip(request)

ipregistry_fastapi/service.py

@@ -0,0 +1,202 @@
+"""
+    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 logging
+from typing import Any, Iterable, Union
+
+from fastapi.requests import HTTPConnection
+from ipregistry import (
+    AsyncIpregistryClient,
+    InMemoryCache,
+    IpInfo,
+    IpregistryConfig,
+    IpregistryError,
+    IpregistryLookupError,
+    NoCache,
+    RequesterIpInfo,
+    UserAgent,
+)
+
+from .exceptions import MissingApiKeyError
+from .ip import IpExtractor, IpSource, anonymize_ip, build_ip_extractor, is_public_ip
+from .settings import IpregistrySettings
+from .version import __version__
+
+logger = logging.getLogger("ipregistry_fastapi")
+
+STATE_KEY = "ipregistry"
+"""Attribute under which the looked up IpInfo is memoized on request.state."""
+
+ERROR_STATE_KEY = "ipregistry_error"
+"""Attribute under which a lookup failure is recorded on request.state."""
+
+
+class Ipregistry:
+    """Request-aware Ipregistry service built on the asynchronous Ipregistry client.
+
+    Explicit lookups (lookup, lookup_batch, lookup_origin, parse_user_agent) raise
+    on failure. The request-aware for_request never raises: it memoizes a single
+    lookup per request on request.state and fails open, recording the error under
+    request.state.ipregistry_error.
+    """
+
+    def __init__(
+        self,
+        settings: IpregistrySettings | None = None,
+        *,
+        client: AsyncIpregistryClient | None = None,
+        ip_extractor: IpSource | None = None,
+    ):
+        self._settings = settings if settings is not None else IpregistrySettings()
+        self._ip_extractor: IpExtractor = build_ip_extractor(
+            ip_extractor if ip_extractor is not None else self._settings.ip_source
+        )
+        if client is None:
+            if not self._settings.api_key:
+                raise MissingApiKeyError()
+            config = IpregistryConfig(
+                key=self._settings.api_key,
+                base_url=self._settings.resolved_base_url,
+                timeout=self._settings.timeout,
+                retry_max_attempts=self._settings.retries + 1,
+                retry_interval=self._settings.retry_interval,
+                retry_on_server_error=self._settings.retry_on_server_error,
+                retry_on_too_many_requests=self._settings.retry_on_too_many_requests,
+                user_agent=f"IpregistryFastAPI/{__version__}",
+            )
+            cache = (
+                InMemoryCache(maxsize=self._settings.cache_max_size, ttl=self._settings.cache_ttl)
+                if self._settings.cache_enabled
+                else NoCache()
+            )
+            client = AsyncIpregistryClient(config, cache=cache)
+        self._client = client
+
+    @property
+    def client(self) -> AsyncIpregistryClient:
+        """The underlying asynchronous Ipregistry client, for advanced use cases
+        such as ASN lookups or credits/throttling introspection."""
+        return self._client
+
+    @property
+    def settings(self) -> IpregistrySettings:
+        return self._settings
+
+    async def aclose(self) -> None:
+        """Release the underlying HTTP resources."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "Ipregistry":
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback) -> None:
+        await self.aclose()
+
+    async def lookup(
+        self,
+        ip: str,
+        *,
+        fields: str | None = None,
+        hostname: bool | None = None,
+        **params: Any,
+    ) -> IpInfo:
+        """Look up IP intelligence for the given address. Raises ApiError or
+        ClientError on failure."""
+        response = await self._client.lookup_ip(ip, **self._options(fields, hostname, params))
+        return response.data
+
+    async def lookup_batch(
+        self,
+        ips: Iterable[str],
+        *,
+        fields: str | None = None,
+        hostname: bool | None = None,
+        **params: Any,
+    ) -> list[Union[IpInfo, IpregistryLookupError]]:
+        """Look up multiple addresses in one round trip. The result preserves
+        input order; failed entries are IpregistryLookupError instances."""
+        response = await self._client.batch_lookup_ips(list(ips), **self._options(fields, hostname, params))
+        return response.data
+
+    async def lookup_origin(
+        self,
+        *,
+        fields: str | None = None,
+        hostname: bool | None = None,
+        **params: Any,
+    ) -> RequesterIpInfo:
+        """Look up IP intelligence for the machine executing this code."""
+        response = await self._client.origin_lookup_ip(**self._options(fields, hostname, params))
+        return response.data
+
+    async def parse_user_agent(self, user_agent: str, **params: Any) -> UserAgent:
+        """Parse a User-Agent header value through the Ipregistry API."""
+        response = await self._client.parse_user_agent(user_agent, **params)
+        return response.data
+
+    def client_ip(self, connection: HTTPConnection) -> str | None:
+        """Resolve the client IP for a request using the configured IP source.
+
+        Returns the configured development_ip when the extracted address is
+        missing or not publicly routable, and None when no usable address
+        remains (private and reserved addresses are never sent to the API).
+        """
+        ip = self._ip_extractor(connection)
+        if ip is not None and is_public_ip(ip):
+            return ip
+        return self._settings.development_ip
+
+    async def for_request(
+        self,
+        connection: HTTPConnection,
+        *,
+        fields: str | None = None,
+        hostname: bool | None = None,
+    ) -> IpInfo | None:
+        """Look up IP intelligence for the request's client, memoized on
+        request.state.ipregistry. Never raises: on failure the request proceeds
+        without data and the error is stored on request.state.ipregistry_error."""
+        state = connection.state
+        if hasattr(state, STATE_KEY):
+            return getattr(state, STATE_KEY)
+
+        info: IpInfo | None = None
+        ip = self.client_ip(connection)
+        if ip is not None:
+            try:
+                info = await self.lookup(ip, fields=fields, hostname=hostname)
+            except IpregistryError as error:
+                setattr(state, ERROR_STATE_KEY, error)
+                logger.warning("Ipregistry lookup failed for %s: %s", anonymize_ip(ip), error)
+        setattr(state, STATE_KEY, info)
+        return info
+
+    @staticmethod
+    def request_error(connection: HTTPConnection) -> IpregistryError | None:
+        """The error recorded by for_request for this request, if any."""
+        return getattr(connection.state, ERROR_STATE_KEY, None)
+
+    def _options(self, fields: str | None, hostname: bool | None, params: dict[str, Any]) -> dict[str, Any]:
+        options = dict(params)
+        resolved_fields = fields if fields is not None else self._settings.fields
+        if resolved_fields:
+            options["fields"] = resolved_fields
+        resolved_hostname = hostname if hostname is not None else self._settings.hostname
+        if resolved_hostname:
+            options["hostname"] = True
+        return options

ipregistry_fastapi/settings.py

@@ -0,0 +1,128 @@
+"""
+    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 pydantic import field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+DEFAULT_BASE_URL = "https://api.ipregistry.co"
+EU_BASE_URL = "https://eu.api.ipregistry.co"
+
+
+class IpregistrySettings(BaseSettings):
+    """Ipregistry configuration, loaded from IPREGISTRY_* environment variables.
+
+    Every field can also be set programmatically:
+    IpregistrySettings(api_key="...", base_url="eu").
+    """
+
+    model_config = SettingsConfigDict(env_prefix="IPREGISTRY_", case_sensitive=False, extra="ignore")
+
+    api_key: str = ""
+    """Your Ipregistry API key. Required unless a pre-configured client is injected."""
+
+    base_url: str | None = None
+    """API base URL. None uses the default endpoint; the shorthand 'eu' selects the
+    EU-only endpoint (https://eu.api.ipregistry.co); any other value is used verbatim."""
+
+    fields: str | None = None
+    """Default field selection applied to lookups (e.g. 'location,security'), reducing
+    payload size and latency. None returns the full response."""
+
+    hostname: bool = False
+    """Whether to resolve the hostname associated with looked up IP addresses."""
+
+    timeout: float = 5.0
+    """Timeout in seconds for API requests. Kept low by default since lookups run on
+    the request path."""
+
+    retries: int = 1
+    """Number of retry attempts after a failed request (0 disables retries)."""
+
+    retry_interval: float = 0.5
+    """Base delay in seconds between retries; grows exponentially with each attempt."""
+
+    retry_on_server_error: bool = True
+    """Whether to retry requests failing with a 5xx status."""
+
+    retry_on_too_many_requests: bool = False
+    """Whether to retry requests failing with a 429 status, honoring Retry-After."""
+
+    cache_enabled: bool = True
+    """Whether to cache lookup responses in memory."""
+
+    cache_max_size: int = 2048
+    """Maximum number of cached lookup responses."""
+
+    cache_ttl: int = 600
+    """Time-to-live in seconds for cached lookup responses."""
+
+    development_ip: str | None = None
+    """Fallback IP address used when the client IP is private or missing, e.g. when
+    developing on localhost. Must be a valid IP address."""
+
+    fail_open: bool = True
+    """When True (default), requests proceed without IP data if a lookup fails.
+    When False, request-aware helpers respond with 503 on lookup failure."""
+
+    ip_source: str = "client"
+    """How to determine the client IP: 'client' (the ASGI client address, honoring
+    your server's proxy-headers configuration), a trusted-proxy preset ('auto',
+    'cloudflare', 'nginx', 'forwarded-for'), or 'header:<name>' for a custom header."""
+
+    @field_validator("ip_source")
+    @classmethod
+    def _validate_ip_source(cls, value: str) -> str:
+        from .ip import build_ip_extractor
+
+        build_ip_extractor(value)  # raises ValueError on unknown sources
+        return value
+
+    @field_validator("development_ip")
+    @classmethod
+    def _validate_development_ip(cls, value: str | None) -> str | None:
+        if value is None or value == "":
+            return None
+        try:
+            ipaddress.ip_address(value)
+        except ValueError as error:
+            raise ValueError(f"development_ip is not a valid IP address: {value!r}") from error
+        return value
+
+    @field_validator("timeout", "retry_interval")
+    @classmethod
+    def _validate_positive(cls, value: float) -> float:
+        if value <= 0:
+            raise ValueError("must be greater than 0")
+        return value
+
+    @field_validator("retries", "cache_max_size", "cache_ttl")
+    @classmethod
+    def _validate_non_negative(cls, value: int) -> int:
+        if value < 0:
+            raise ValueError("must not be negative")
+        return value
+
+    @property
+    def resolved_base_url(self) -> str:
+        if not self.base_url:
+            return DEFAULT_BASE_URL
+        if self.base_url.strip().lower() == "eu":
+            return EU_BASE_URL
+        return self.base_url

ipregistry_fastapi/testing.py

@@ -0,0 +1,186 @@
+"""
+    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 Any, Iterable, Mapping, Union
+
+from fastapi.requests import HTTPConnection
+from ipregistry import ApiError, IpInfo, IpregistryError, IpregistryLookupError, RequesterIpInfo, UserAgent
+
+from .ip import IpSource, is_valid_ip
+from .service import Ipregistry
+from .settings import IpregistrySettings
+
+ResponseStub = Union[Mapping[str, Any], IpInfo, Exception]
+
+WILDCARD = "*"
+ORIGIN = "origin"
+
+
+class _UnusedClient:
+    """Placeholder ensuring an IpregistryFake never reaches the network."""
+
+    def __getattr__(self, name: str):
+        raise AssertionError("IpregistryFake performs no real API calls")
+
+
+class IpregistryFake(Ipregistry):
+    """Drop-in Ipregistry service for tests: no network, canned responses.
+
+    Responses are keyed by IP address; '*' matches any address and 'origin'
+    serves origin lookups. A value may be an API-shaped dict (the 'ip' field is
+    filled in automatically), an IpInfo instance, or an exception to raise:
+
+        fake = IpregistryFake({
+            "66.165.2.7": {"location": {"country": {"code": "US"}}},
+            "*": {"security": {"is_threat": False}},
+        })
+        add_ipregistry(app, service=fake)
+
+    Unlike the real service, private and loopback client addresses are used
+    verbatim so requests made through TestClient resolve out of the box.
+    Lookups without a matching stub raise an ApiError (which request-aware
+    helpers turn into a fail-open None).
+    """
+
+    def __init__(
+        self,
+        responses: Mapping[str, ResponseStub] | None = None,
+        *,
+        settings: IpregistrySettings | None = None,
+        ip_extractor: IpSource | None = None,
+    ):
+        super().__init__(
+            settings if settings is not None else IpregistrySettings(api_key="fake"),
+            client=_UnusedClient(),  # type: ignore[arg-type]
+            ip_extractor=ip_extractor,
+        )
+        self._responses: dict[str, ResponseStub] = {}
+        self.lookups: list[str] = []
+        self.origin_lookups: int = 0
+        self.parsed_user_agents: list[str] = []
+        if responses:
+            self.stub(responses)
+
+    def stub(self, responses: Mapping[str, ResponseStub]) -> "IpregistryFake":
+        """Register additional canned responses, keyed by IP ('*', 'origin')."""
+        self._responses.update(responses)
+        return self
+
+    def reset(self) -> "IpregistryFake":
+        """Clear all recorded lookups."""
+        self.lookups.clear()
+        self.origin_lookups = 0
+        self.parsed_user_agents.clear()
+        return self
+
+    async def aclose(self) -> None:
+        pass
+
+    async def lookup(self, ip: str, *, fields=None, hostname=None, **params: Any) -> IpInfo:
+        self.lookups.append(ip)
+        stub = self._resolve_stub(ip)
+        if isinstance(stub, Exception):
+            raise stub
+        if isinstance(stub, IpInfo):
+            return stub
+        data = dict(stub)
+        data.setdefault("ip", ip if is_valid_ip(ip) else None)
+        return IpInfo(**data)
+
+    async def lookup_batch(self, ips: Iterable[str], *, fields=None, hostname=None, **params: Any):
+        results: list[Union[IpInfo, IpregistryLookupError]] = []
+        for ip in ips:
+            try:
+                results.append(await self.lookup(ip, fields=fields, hostname=hostname, **params))
+            except IpregistryLookupError as error:
+                results.append(error)
+            except IpregistryError as error:
+                results.append(IpregistryLookupError({"code": "UNKNOWN", "message": str(error), "resolution": ""}))
+        return results
+
+    async def lookup_origin(self, *, fields=None, hostname=None, **params: Any) -> RequesterIpInfo:
+        self.origin_lookups += 1
+        stub = self._responses.get(ORIGIN)
+        if stub is None:
+            raise self._missing(ORIGIN)
+        if isinstance(stub, Exception):
+            raise stub
+        if isinstance(stub, RequesterIpInfo):
+            return stub
+        if isinstance(stub, IpInfo):
+            return RequesterIpInfo(**stub.model_dump())
+        return RequesterIpInfo(**dict(stub))
+
+    async def parse_user_agent(self, user_agent: str, **params: Any) -> UserAgent:
+        self.parsed_user_agents.append(user_agent)
+        stub = self._responses.get(user_agent)
+        if isinstance(stub, Exception):
+            raise stub
+        if isinstance(stub, Mapping):
+            data = dict(stub)
+            data.setdefault("header", user_agent)
+            return UserAgent(**data)
+        return UserAgent(header=user_agent)
+
+    def client_ip(self, connection: HTTPConnection) -> str | None:
+        ip = self._ip_extractor(connection)
+        if ip:
+            return ip
+        if connection.client is not None and connection.client.host:
+            return connection.client.host
+        return self.settings.development_ip
+
+    # Assertions
+
+    def assert_looked_up(self, ip: str) -> None:
+        assert ip in self.lookups, f"Expected a lookup for {ip!r}; recorded lookups: {self.lookups!r}"
+
+    def assert_not_looked_up(self, ip: str) -> None:
+        assert ip not in self.lookups, f"Did not expect a lookup for {ip!r}"
+
+    def assert_looked_up_times(self, ip: str, times: int) -> None:
+        count = self.lookups.count(ip)
+        assert count == times, f"Expected {times} lookup(s) for {ip!r}, recorded {count}"
+
+    def assert_nothing_looked_up(self) -> None:
+        assert not self.lookups and self.origin_lookups == 0, (
+            f"Expected no lookups; recorded lookups: {self.lookups!r}, origin lookups: {self.origin_lookups}"
+        )
+
+    def assert_origin_looked_up(self) -> None:
+        assert self.origin_lookups > 0, "Expected at least one origin lookup"
+
+    def assert_user_agents_parsed(self, *user_agents: str) -> None:
+        for user_agent in user_agents:
+            assert user_agent in self.parsed_user_agents, (
+                f"Expected {user_agent!r} to be parsed; recorded: {self.parsed_user_agents!r}"
+            )
+
+    def _resolve_stub(self, ip: str) -> ResponseStub:
+        stub = self._responses.get(ip, self._responses.get(WILDCARD))
+        if stub is None:
+            raise self._missing(ip)
+        return stub
+
+    @staticmethod
+    def _missing(key: str) -> ApiError:
+        return ApiError(
+            "FAKE_RESPONSE_MISSING",
+            f"No fake response registered for {key!r}.",
+            "Register a response with IpregistryFake({...}) or a '*' wildcard entry.",
+        )

ipregistry_fastapi/version.py

@@ -0,0 +1,17 @@
+"""
+    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.
+"""
+
+__version__ = "1.0.0"