xtr-http-foundation 4.0.2__py3-none-any.whl

xtr_http_foundation/.agents/skills/xtr-http-foundation/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: xtr-http-foundation
+description: How to say "is this request one of mine" with xtr-http-foundation — one matcher per question about a request that arrived (method, path, host, port, scheme, a header, a query parameter, an attribute, the address it came from, a JSON body), chained into one, plus the IpUtils helpers that place an IP in a network, name a private one, or anonymize it. Use when a firewall, webhook endpoint, rate limiter, router or middleware has to decide which requests it claims; when replacing a tangle of ifs over the method and path with something testable; when writing a request parser's matcher; and when checking whether an address is inside a subnet, is reachable only from this network, or must be logged without identifying one machine.
+---
+
+# xtr-http-foundation
+
+A matcher answers one question about a request that arrived, and a chain of them answers the
+whole of it — so what a piece of code claims is a value it can be handed rather than a
+condition written into it. Beside them live the address helpers those questions are built on.
+
+## Quick reference
+
+- Every matcher is a `RequestMatcherInterface` with one member:
+  `await matcher.matches(request)` → `bool`. The request is a `ServerRequestInterface`.
+- `matches()` is awaited even on a matcher that only reads the head, so one can be swapped for
+  another.
+- `ChainRequestMatcher([...])` claims a request only when all of them do, answering on the
+  first refusal. A chain of nothing claims everything.
+- A matcher naming nothing claims everything. One string is as good as a sequence, and any
+  entry may hold a comma-separated list.
+- Expressions are compiled when the matcher is built — a bad one is `InvalidArgumentError`
+  there — and are *searched for*, never anchored for you.
+- `IpUtils.check_ip`, `check_ip4`, `check_ip6`, `is_private_ip`, `anonymize`,
+  `IpUtils.PRIVATE_SUBNETS`. All static; there is nothing to build.
+
+## Claim the requests that are yours
+
+```python
+from xtr_http_foundation import (
+    ChainRequestMatcher,
+    IsJsonRequestMatcher,
+    MethodRequestMatcher,
+    PathRequestMatcher,
+)
+
+ours = ChainRequestMatcher(
+    [MethodRequestMatcher("POST"), PathRequestMatcher("^/webhook/"), IsJsonRequestMatcher()]
+)
+
+if await ours.matches(request):
+    ...
+```
+
+| Matcher | Takes | Claims a request |
+| --- | --- | --- |
+| `MethodRequestMatcher(methods)` | one method or several | whose method is one of them; names read in upper case, the request's compared as it arrived |
+| `PathRequestMatcher(regexp)` | one expression | whose path matches it |
+| `HostRequestMatcher(regexp)` | one expression | whose host matches it, without regard to case |
+| `PortRequestMatcher(port)` | one port | asked of that port, the scheme's standard one counting where the URI is silent |
+| `SchemeRequestMatcher(schemes)` | one scheme or several | made over one of them |
+| `HeaderRequestMatcher(headers)` | header names | carrying every one, whatever each holds |
+| `QueryParameterRequestMatcher(parameters)` | parameter names | whose query *opens* with them, in that order |
+| `IpsRequestMatcher(ips)` | addresses or CIDR networks | that came from one of them |
+| `AttributesRequestMatcher(regexps)` | attribute name → expression | whose every named attribute matches its own |
+| `IsJsonRequestMatcher()` | nothing | whose body reads as JSON |
+| `ChainRequestMatcher(matchers)` | matchers | every one of them claims |
+
+Three behave in a way worth knowing before you rely on them.
+
+- **`IsJsonRequestMatcher` reads the body, not the `Content-Type` header.** A sender that
+  announces nothing still sent JSON; one that announces JSON and sent something else did not.
+  Any JSON value counts, so this is the rule for "a body worth decoding" rather than for a
+  shape. The body is read from its first byte — a stream another matcher already read is
+  rewound — so the order of a chain changes nothing, and a body that cannot be read is simply
+  not claimed.
+- **`IpsRequestMatcher` reads the address the server accepted the connection from**, which the
+  request carries among its server parameters under `client`. A request through a proxy comes
+  *from the proxy*; a rule about the original caller belongs where the forwarded headers are
+  trusted and resolved.
+- **`PathRequestMatcher` matches the path the application itself sees**, with the mount
+  (`root_path` among the server parameters) removed and per cent escapes undone — so
+  `/admin/fo o` matches `/admin/fo%20o`, and moving the mount rewrites no matcher. Nothing in
+  the expression is a path parameter: `^/{_locale}/login$` matches those very braces.
+
+```python
+from xtr_http_foundation import AttributesRequestMatcher, HostRequestMatcher, IpsRequestMatcher
+
+internal = IpsRequestMatcher("10.0.0.0/8,192.168.1.7")
+subdomain = HostRequestMatcher(r"\.example\.com$")
+owners = AttributesRequestMatcher({"role": "^owner$"})
+```
+
+An attribute the request does not carry, or carries as something that is not text, is never
+claimed.
+
+## Write a matcher
+
+`RequestMatcherInterface` is a `@runtime_checkable` `Protocol`, so no base class is needed:
+
+```python
+from typing import final
+
+from typing_extensions import override
+from xtr_http_foundation import RequestMatcherInterface
+from xtr_http_message_contracts import ServerRequestInterface
+
+
+@final
+class SignedRequestMatcher(RequestMatcherInterface):
+    __slots__ = ()
+
+    @override
+    async def matches(self, request: ServerRequestInterface) -> bool:
+        return request.has_header("Webhook-Signature")
+```
+
+## Place an address
+
+```python
+from xtr_http_foundation import IpUtils
+
+IpUtils.check_ip("10.1.2.3", ["192.168.0.0/16", "10.0.0.0/8"])  # True
+IpUtils.check_ip4("10.1.2.3", "10.0.0.0/8")  # True
+IpUtils.check_ip6("::1", "::1/128")  # True
+IpUtils.is_private_ip("10.1.2.3")  # True
+IpUtils.anonymize("192.168.1.42")  # "192.168.1.0"
+IpUtils.anonymize("2001:db8::1")  # "2001:db8::"
+```
+
+- `check_ip` takes a single address, a CIDR network, or several of either, and picks the IPv4 or
+  the IPv6 check by how the address is written.
+- **The checks never raise over unreadable text**: they answer about a request from a stranger,
+  and an address nobody can read is one no network holds. A network written wrongly is read as
+  no network rather than as a wider one — `" 8"`, `"+8"`, `"8.5"` name no prefix length — and an
+  IPv6 zone such as `fe80::1%eth0` is refused, since it names an interface of whichever host
+  reads it.
+- `is_private_ip` is the one that **does** raise `InvalidArgumentError` for text that is no
+  address: its caller is asking whether an address may be reached out to. It places the address
+  in `IpUtils.PRIVATE_SUBNETS` — loopback, private use, link-local, carrier-grade NAT,
+  unique-local, multicast, reserved, unspecified, the documentation and benchmarking ranges, and
+  the forms an IPv6 address writes an IPv4 one in.
+- `anonymize(ip, v4_bytes=1, v6_bytes=8)` zeroes the last bytes and gives the address back as it
+  arrived — bracketed if it was, dotted where it carries an IPv4 one, and never with its zone.
+  Fewer than no bytes, or more than the address has, is `InvalidArgumentError`.
+
+## Testing
+
+A matcher is a value, so a test hands it a request it built and asserts the one answer:
+
+```python
+import pytest
+from xtr_http_foundation import IpsRequestMatcher, MethodRequestMatcher
+from xtr_http_message import ServerRequest
+
+
+@pytest.mark.anyio
+async def test_it_claims_a_post_from_inside_the_network() -> None:
+    matcher = IpsRequestMatcher("10.0.0.0/8")
+    arrived = ServerRequest("POST", "/metrics", server_params={"client": ("10.1.2.3", 51234)})
+
+    assert await matcher.matches(arrived)
+    assert await MethodRequestMatcher("POST").matches(arrived)
+```
+
+- Build requests with `ServerRequest(method, uri, headers, body, version, server_params)` from
+  [xtr-http-message](https://github.com/xterr/python-xtr/tree/main/packages/xtr-http-message)
+  — a dev dependency here, since only tests build a request.
+- Give `server_params={"client": (address, port)}` for `IpsRequestMatcher` and
+  `server_params={"root_path": "/mounted"}` for `PathRequestMatcher`; without them each reads
+  as nothing supplied.
+- Set what `AttributesRequestMatcher` reads with `request.with_attribute(name, value)`.
+- Pass the body as bytes for `IsJsonRequestMatcher`; nothing has to be rewound by hand.
+
+## Use in an application
+
+This package **ships no bundle and no recipe**: a matcher is a value built where the rule is
+written, not a service to configure.
+
+1. **Install** — `uv add xtr-http-foundation`. There are no extras.
+2. **Activate** — nothing to do. Nothing is registered, so nothing is listed in `BUNDLES`.
+3. **Configure** — nothing. Build the matchers where the rule belongs, usually in the class
+   that asks the question.
+4. **Environment** and **Ignore** — nothing.
+5. **Check** — the test above: a matcher is testable on its own, which is the point of it.
+6. **Remove** — `uv remove xtr-http-foundation`.
+
+Packages that *do* wire these for you say so in their own sections: a
+[xtr-webhook](https://github.com/xterr/python-xtr/tree/main/packages/xtr-webhook) parser
+returns one from `get_request_matcher()`, and
+[xtr-http-client](https://github.com/xterr/python-xtr/tree/main/packages/xtr-http-client)'s
+`NoPrivateNetworkHttpClient` guards `IpUtils.PRIVATE_SUBNETS` by default.
+
+## Errors
+
+Everything derives from `HttpFoundationError`. There is one: `InvalidArgumentError`, also a
+`ValueError`, raised for an expression that does not read as one, and by `is_private_ip` and
+`anonymize` for text that is no address.
+
+## Do not
+
+- Do not check `Content-Type` to decide whether a body is JSON — `IsJsonRequestMatcher` reads
+  the body, which is the only thing that settles it.
+- Do not trust `IpsRequestMatcher` for the original caller behind a proxy; resolve the forwarded
+  headers first, where they are trusted.
+- Do not expect an expression to be anchored: `PathRequestMatcher("/admin")` claims anything
+  containing that path. Write `^/admin/` when that is the rule.
+- Do not write path parameters into a `PathRequestMatcher` expression — `{id}` matches braces.
+- Do not pass host names to `IpsRequestMatcher` or to the `IpUtils` checks: they place
+  addresses, and a name would have to be resolved first.
+- Do not call `matches()` without awaiting it — every matcher is async, including the ones that
+  only read the head.
+- Do not pass an empty matcher expecting it to refuse everything: a matcher naming nothing
+  claims every request.

xtr_http_foundation/__init__.py

@@ -0,0 +1,44 @@
+"""The request surface an incoming HTTP request is matched and measured against.
+
+A matcher answers one question about a request that arrived — its method, path, host, port,
+scheme, a header, a query parameter, an attribute, the address it came from, or whether its
+body is JSON — and a chain of them answers the whole of it, so what a piece of code claims is
+a value it can be handed rather than a condition written into it.
+
+Beside them are the address helpers those questions are built on: whether an IP falls inside a
+network, and whether it is one only this network can reach.
+"""
+
+from __future__ import annotations
+
+from .chain_request_matcher import ChainRequestMatcher
+from .ip_utils import IpUtils
+from .request_matcher import (
+    AttributesRequestMatcher,
+    HeaderRequestMatcher,
+    HostRequestMatcher,
+    IpsRequestMatcher,
+    IsJsonRequestMatcher,
+    MethodRequestMatcher,
+    PathRequestMatcher,
+    PortRequestMatcher,
+    QueryParameterRequestMatcher,
+    SchemeRequestMatcher,
+)
+from .request_matcher_interface import RequestMatcherInterface
+
+__all__ = [
+    "AttributesRequestMatcher",
+    "ChainRequestMatcher",
+    "HeaderRequestMatcher",
+    "HostRequestMatcher",
+    "IpUtils",
+    "IpsRequestMatcher",
+    "IsJsonRequestMatcher",
+    "MethodRequestMatcher",
+    "PathRequestMatcher",
+    "PortRequestMatcher",
+    "QueryParameterRequestMatcher",
+    "RequestMatcherInterface",
+    "SchemeRequestMatcher",
+]

xtr_http_foundation/chain_request_matcher.py

@@ -0,0 +1,55 @@
+"""A matcher that claims a request only when every matcher it holds does."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+
+from .request_matcher_interface import RequestMatcherInterface
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from xtr_http_message_contracts import ServerRequestInterface
+
+__all__ = ["ChainRequestMatcher"]
+
+
+@final
+class ChainRequestMatcher(RequestMatcherInterface):
+    """Claims a request only when every matcher it chains claims it.
+
+    What a piece of code will look at is usually more than one thing — a
+    ``POST``, carrying JSON, from inside this network — and this is how those
+    are said together without any matcher learning about the others.
+
+    A chain of nothing claims every request: nothing constrains it, so there is
+    nothing for it to refuse.
+    """
+
+    __slots__ = ("_matchers",)
+
+    def __init__(self, matchers: Iterable[RequestMatcherInterface]) -> None:
+        """Record the matchers that must all claim a request.
+
+        Args:
+            matchers: The matchers to chain. Read once and kept, so a chain
+                built over a generator answers the same on every request, and
+                a sequence the caller goes on to change cannot alter what the
+                chain claims.
+        """
+        self._matchers: tuple[RequestMatcherInterface, ...] = tuple(matchers)
+
+    @override
+    async def matches(self, request: ServerRequestInterface) -> bool:
+        """Tell whether every chained matcher claims ``request``.
+
+        The first refusal is the answer, so a matcher that reads the body is
+        never asked for a request an earlier one already turned away.
+        """
+        for matcher in self._matchers:
+            if not await matcher.matches(request):
+                return False
+
+        return True

xtr_http_foundation/exception/__init__.py

@@ -0,0 +1,12 @@
+"""Every error this library raises.
+
+All of them derive from :class:`HttpFoundationError`, so one ``except`` catches anything
+this library refuses, and a narrower one handles a single cause.
+"""
+
+from __future__ import annotations
+
+from .http_foundation_error import HttpFoundationError
+from .invalid_argument_error import InvalidArgumentError
+
+__all__ = ["HttpFoundationError", "InvalidArgumentError"]

xtr_http_foundation/exception/http_foundation_error.py

@@ -0,0 +1,9 @@
+"""The error every other error of this package derives from."""
+
+from __future__ import annotations
+
+__all__ = ["HttpFoundationError"]
+
+
+class HttpFoundationError(Exception):
+    """Something asked of this library that it cannot do — catch this to catch them all."""

xtr_http_foundation/exception/invalid_argument_error.py

@@ -0,0 +1,18 @@
+"""A value handed to this library cannot be used."""
+
+from __future__ import annotations
+
+from .http_foundation_error import HttpFoundationError
+
+__all__ = ["InvalidArgumentError"]
+
+
+class InvalidArgumentError(HttpFoundationError, ValueError):
+    """A value handed to this library cannot be used: text that is not an address.
+
+    Also a :class:`ValueError`, so code that already guards against a bad value
+    catches it without knowing this library exists. It says a caller passed
+    something it cannot have meant, which is why the checks that *decide* about a
+    request — whether an address falls in a network — answer ``False`` instead of
+    raising: an address that does not parse is simply not in the network.
+    """

xtr_http_foundation/ip_utils.py

@@ -0,0 +1,245 @@
+"""Placing an IP address inside a network, and hiding where it came from."""
+
+from __future__ import annotations
+
+import socket
+from ipaddress import IPv4Address, IPv4Network, IPv6Address, IPv6Network
+from typing import TYPE_CHECKING, Final, final
+
+from .exception import InvalidArgumentError
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["IpUtils"]
+
+_V4_BYTES: Final = 4
+_V6_BYTES: Final = 16
+_V4_BITS: Final = 32
+_V6_BITS: Final = 128
+
+# How an IPv6 address says it carries an IPv4 one: "::ffff:1.2.3.4" is the form in use,
+# "::1.2.3.4" the one that came before it. What identifies an address as either is the
+# bytes in front, so anonymizing one means dropping bytes from its four, not its sixteen.
+_V4_MAPPED: Final = b"\x00" * 10 + b"\xff\xff"
+_V4_COMPATIBLE: Final = b"\x00" * 12
+
+
+def _as_ipv4(text: str) -> IPv4Address | None:
+    """The IPv4 address ``text`` writes, or ``None`` when it writes none."""
+    try:
+        return IPv4Address(text)
+    except ValueError:
+        return None
+
+
+def _as_ipv6(text: str) -> IPv6Address | None:
+    """The IPv6 address ``text`` writes, or ``None`` when it writes none.
+
+    A zone — the ``%eth0`` of ``fe80::1%eth0`` — names an interface of whichever host
+    reads it, so the same text means a different address on the next machine. Nothing can
+    be decided from one, and it is refused here rather than quietly dropped.
+    """
+    if "%" in text:
+        return None
+    try:
+        return IPv6Address(text)
+    except ValueError:
+        return None
+
+
+def _prefix_length(text: str, longest: int) -> int | None:
+    """The CIDR prefix length ``text`` writes, or ``None`` when it writes none.
+
+    Only ASCII digits count, so ``" 8"``, ``"+8"``, ``"8e0"`` and ``"8.5"`` name no prefix
+    at all rather than the 8 a lenient reader would take from each of them — a network
+    written wrongly must not silently become a wider one.
+    """
+    if not (text.isascii() and text.isdigit()):
+        return None
+    length = int(text)
+    return length if length <= longest else None
+
+
+def _masked(packed: bytes, mask: bytes) -> bytes:
+    """``packed`` with every byte the mask does not keep zeroed."""
+    return bytes(byte & keep for byte, keep in zip(packed, mask, strict=True))
+
+
+@final
+class IpUtils:
+    """Where an address sits: in a network, in a private one, or hidden by its last bytes.
+
+    A namespace rather than something to build — every answer here is a function of its
+    arguments. Text that is not an address is no error for the checks: they answer about a
+    request from a stranger, whose address is theirs to misspell, and an address nobody
+    can read is one no network holds.
+    """
+
+    __slots__ = ()
+
+    #: The networks an address in them can only be reached from inside this network.
+    PRIVATE_SUBNETS: Final[tuple[str, ...]] = (
+        "127.0.0.0/8",  # loopback
+        "10.0.0.0/8",  # private use
+        "192.168.0.0/16",  # private use
+        "192.0.0.0/24",  # assigned to protocols rather than to hosts
+        "192.0.2.0/24",  # reserved for documentation
+        "198.51.100.0/24",  # reserved for documentation
+        "203.0.113.0/24",  # reserved for documentation
+        "172.16.0.0/12",  # private use
+        "169.254.0.0/16",  # link local
+        "192.88.99.0/24",  # 6to4 relay anycast, withdrawn
+        "198.18.0.0/15",  # reserved for benchmarking
+        "0.0.0.0/8",  # this network
+        "240.0.0.0/4",  # reserved
+        "100.64.0.0/10",  # shared address space, between a provider and its subscribers
+        "224.0.0.0/4",  # multicast
+        "::1/128",  # loopback
+        "fc00::/7",  # unique local
+        "fe80::/10",  # link local
+        "::ffff:0:0/96",  # an IPv4 address written as an IPv6 one
+        "::/128",  # unspecified
+        "::/96",  # an IPv4 address written as an IPv6 one, in the earlier form
+        "100::/64",  # discard only
+        "2002::/16",  # 6to4
+        "2001::/32",  # Teredo tunnelling
+        "2001:db8::/32",  # reserved for documentation
+        "2001:0002::/48",  # reserved for benchmarking
+        "64:ff9b::/96",  # the well-known prefix translating IPv4 to IPv6
+        "64:ff9b:1::/48",  # the same translation, for local use
+        "ff00::/8",  # multicast
+    )
+
+    @staticmethod
+    def check_ip(request_ip: str, ips: str | Sequence[str]) -> bool:
+        """Whether ``request_ip`` falls in any of ``ips``.
+
+        Args:
+            request_ip: the address to place, written as IPv4 or IPv6.
+            ips: a network in CIDR notation, a single address, or several of either.
+
+        Returns:
+            Whether any of them holds the address; ``False`` for text that is no address.
+        """
+        networks = (ips,) if isinstance(ips, str) else ips
+        # More than one colon is what only an IPv6 address has — "::1" has two, while an
+        # IPv4 address carrying a port would have one.
+        check = IpUtils.check_ip6 if request_ip.count(":") > 1 else IpUtils.check_ip4
+        return any(check(request_ip, network) for network in networks)
+
+    @staticmethod
+    def check_ip4(request_ip: str, ip: str) -> bool:
+        """Whether ``request_ip`` falls in the IPv4 network or address ``ip``.
+
+        Args:
+            request_ip: the address to place, written as IPv4.
+            ip: a network in CIDR notation, or a single address, which stands for itself.
+
+        Returns:
+            Whether the network holds the address; ``False`` when either is no IPv4 one.
+        """
+        address = _as_ipv4(request_ip)
+        if address is None:
+            return False
+        network_text, separator, prefix_text = ip.partition("/")
+        network_address = _as_ipv4(network_text)
+        if network_address is None:
+            return False
+        prefix = _prefix_length(prefix_text, _V4_BITS) if separator else _V4_BITS
+        if prefix is None:
+            return False
+        return address in IPv4Network((network_address, prefix), strict=False)
+
+    @staticmethod
+    def check_ip6(request_ip: str, ip: str) -> bool:
+        """Whether ``request_ip`` falls in the IPv6 network or address ``ip``.
+
+        Args:
+            request_ip: the address to place, written as IPv6.
+            ip: a network in CIDR notation, or a single address, which stands for itself.
+
+        Returns:
+            Whether the network holds the address; ``False`` when either is no IPv6 one.
+        """
+        address = _as_ipv6(request_ip)
+        if address is None:
+            return False
+        network_text, separator, prefix_text = ip.partition("/")
+        network_address = _as_ipv6(network_text)
+        if network_address is None:
+            return False
+        prefix = _prefix_length(prefix_text, _V6_BITS) if separator else _V6_BITS
+        if prefix is None:
+            return False
+        return address in IPv6Network((network_address, prefix), strict=False)
+
+    @staticmethod
+    def anonymize(ip: str, v4_bytes: int = 1, v6_bytes: int = 8) -> str:
+        """``ip`` with its last bytes zeroed, so what is left no longer names one machine.
+
+        Args:
+            ip: the address to hide, bracketed or carrying a zone if that is how it came.
+            v4_bytes: how many of an IPv4 address's four bytes to drop.
+            v6_bytes: how many of an IPv6 address's sixteen bytes to drop.
+
+        Returns:
+            The address written as it arrived: bracketed if it was, and dotted where it
+            carries an IPv4 one. A zone is never given back — it names an interface, which
+            is as much a trace of who was asked as the bytes just dropped.
+
+        Raises:
+            InvalidArgumentError: when asked for fewer than no bytes, for more than the
+                address has, or for text that is no address at all.
+        """
+        if v4_bytes < 0 or v6_bytes < 0:
+            raise InvalidArgumentError("Cannot anonymize less than 0 bytes.")
+        if v4_bytes > _V4_BYTES or v6_bytes > _V6_BYTES:
+            raise InvalidArgumentError(
+                "Cannot anonymize more than 4 bytes for IPv4 and 16 bytes for IPv6."
+            )
+
+        text = ip.partition("%")[0]
+        wrapped = text.startswith("[") and text.endswith("]")
+        if wrapped:
+            text = text[1:-1]
+        address: IPv4Address | IPv6Address | None = _as_ipv4(text) or _as_ipv6(text)
+        if address is None:
+            raise InvalidArgumentError(f'"{ip}" is not a valid IP address.')
+
+        tail = b"\xff" * (_V4_BYTES - v4_bytes) + b"\x00" * v4_bytes
+        packed = address.packed
+        if isinstance(address, IPv4Address):
+            anonymized = str(IPv4Address(_masked(packed, tail)))
+        else:
+            if packed.startswith(_V4_MAPPED):
+                mask = _V4_MAPPED + tail
+            elif packed.startswith(_V4_COMPATIBLE):
+                mask = _V4_COMPATIBLE + tail
+            else:
+                mask = b"\xff" * (_V6_BYTES - v6_bytes) + b"\x00" * v6_bytes
+            # `ipaddress` writes every group as hexadecimal, which would turn an address
+            # carrying an IPv4 one into "::ffff:7bea:eb00" — the same bytes, no longer
+            # recognisable as the address that went in. `inet_ntop` keeps the dotted form.
+            anonymized = socket.inet_ntop(socket.AF_INET6, _masked(packed, mask))
+        return f"[{anonymized}]" if wrapped else anonymized
+
+    @staticmethod
+    def is_private_ip(ip: str) -> bool:
+        """Whether ``ip`` is an address only this network can reach.
+
+        Args:
+            ip: the address to place, written as IPv4 or IPv6.
+
+        Returns:
+            Whether it falls in any of :attr:`PRIVATE_SUBNETS`.
+
+        Raises:
+            InvalidArgumentError: when ``ip`` is not an address written plainly. This one
+                refuses where the checks above answer, because its caller is asking
+                whether an address may be reached out to, and text nobody can read is not
+                an address that failed the question — it is a question nobody can answer.
+        """
+        if _as_ipv4(ip) is None and _as_ipv6(ip) is None:
+            raise InvalidArgumentError(f'"{ip}" is not a valid IP address.')
+        return IpUtils.check_ip(ip, IpUtils.PRIVATE_SUBNETS)

xtr_http_foundation/request_matcher/__init__.py

@@ -0,0 +1,27 @@
+"""One matcher per question worth asking about a request that arrived."""
+
+from __future__ import annotations
+
+from .attributes_request_matcher import AttributesRequestMatcher
+from .header_request_matcher import HeaderRequestMatcher
+from .host_request_matcher import HostRequestMatcher
+from .ips_request_matcher import IpsRequestMatcher
+from .is_json_request_matcher import IsJsonRequestMatcher
+from .method_request_matcher import MethodRequestMatcher
+from .path_request_matcher import PathRequestMatcher
+from .port_request_matcher import PortRequestMatcher
+from .query_parameter_request_matcher import QueryParameterRequestMatcher
+from .scheme_request_matcher import SchemeRequestMatcher
+
+__all__ = [
+    "AttributesRequestMatcher",
+    "HeaderRequestMatcher",
+    "HostRequestMatcher",
+    "IpsRequestMatcher",
+    "IsJsonRequestMatcher",
+    "MethodRequestMatcher",
+    "PathRequestMatcher",
+    "PortRequestMatcher",
+    "QueryParameterRequestMatcher",
+    "SchemeRequestMatcher",
+]

xtr_http_foundation/request_matcher/_comma_separated.py

@@ -0,0 +1,32 @@
+"""Reading one name, or several, out of what a matcher was given."""
+
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["comma_separated"]
+
+_SEPARATOR: Final = re.compile(r"\s*,\s*")
+
+
+def comma_separated(given: Sequence[str] | str) -> tuple[str, ...]:
+    """Return every name ``given`` holds, however they were written.
+
+    A matcher takes one name or a list of them, and each of those may itself
+    hold several separated by commas — so a name read from configuration, where
+    a list is awkward to write, reaches the matcher the same way a list does.
+    Whitespace around a comma belongs to the separator rather than to a name.
+
+    Args:
+        given: One name, or several; any of them may be a comma-separated list.
+
+    Returns:
+        The names, in the order they were written.
+    """
+    values = (given,) if isinstance(given, str) else given
+
+    return tuple(name for value in values for name in _SEPARATOR.split(value))