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

xtr_http_client/http_client_mixin.py

@@ -0,0 +1,176 @@
+"""The work every client here does before a connection is opened."""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+from collections.abc import Sequence
+from typing import TYPE_CHECKING, Final, Self
+
+from typing_extensions import Unpack
+from xtr_http_client_contracts import OPTIONS_DEFAULTS
+
+from xtr_http_client.exception import InvalidArgumentError
+from xtr_http_client.internal import option_merge
+from xtr_http_client.internal.debug_type import debug_type
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from xtr_http_client_contracts import RequestOptions
+
+__all__ = ["HttpClientMixin"]
+
+_AUTH_BASIC_PARTS: Final = (1, 2)
+_UNPRINTABLE: Final = re.compile(r"[^\x21-\x7E]")
+_NO_BODY: Final = (None, b"", "")
+
+
+class HttpClientMixin:
+    """What a client refuses, and the options it starts every request from.
+
+    Mixed into every client here, so all of them keep their defaults the same
+    way and refuse the same requests — which is what lets one be swapped for
+    another without a caller noticing. A client is then only the part that
+    opens connections.
+
+    Its own state is the one thing a client needs from it: the options every
+    request starts from. ``__init__`` takes them so a subclass can hand over
+    what it was built with and get back the merged defaults.
+
+    The checks are exposed one by one because a client makes them one at a
+    time: the method is known before the options are read, and a client
+    preparing its own defaults has no method to check at all.
+    """
+
+    __slots__: tuple[str, ...] = ("_default_options",)
+
+    _default_options: dict[str, object]
+
+    def __init__(self, default_options: RequestOptions | None = None) -> None:
+        """Start from the contract's defaults, with ``default_options`` over them.
+
+        Raises:
+            InvalidArgumentError: When an option is not one this client knows.
+        """
+        self._default_options = dict(OPTIONS_DEFAULTS)
+        if default_options:
+            self._default_options = self.merge_default_options(
+                default_options,
+                self._default_options,
+            )
+
+    def with_options(self, **options: Unpack[RequestOptions]) -> Self:
+        """A copy of this client whose defaults have ``options`` over them.
+
+        A copy rather than a change, so a caller can narrow a client for one
+        job — a header, a timeout, a base URI — without the client everyone
+        else holds changing under them.
+
+        Raises:
+            InvalidArgumentError: When an option is not one this client knows.
+        """
+        clone = copy.copy(self)
+        # The clone is this very class, and its defaults are the one thing
+        # about it that has to change; there is no other way to seed them.
+        clone._default_options = self.merge_default_options(  # noqa: SLF001 — same class
+            options,
+            self._default_options,
+        )
+
+        return clone
+
+    @classmethod
+    def merge_default_options(
+        cls,
+        options: Mapping[str, object],
+        default_options: Mapping[str, object],
+    ) -> dict[str, object]:
+        """Merge what a request asked for over what the client always asks for.
+
+        See :func:`xtr_http_client.internal.option_merge.merge_default_options`.
+        """
+        return option_merge.merge_default_options(
+            cls.__qualname__,
+            options,
+            default_options,
+        )
+
+    def validate_options(self, options: Mapping[str, object]) -> None:
+        """Refuse an option this client does not know, naming the closest it does.
+
+        See :func:`xtr_http_client.internal.option_merge.validate_options`.
+        """
+        option_merge.validate_options(type(self).__qualname__, options, self._default_options)
+
+    @staticmethod
+    def validate_method(method: str) -> None:
+        """Refuse a method no server would read as the one that was meant.
+
+        Raises:
+            InvalidArgumentError: When the method is empty, or is anything
+                other than uppercase ASCII letters.
+        """
+        if method == "":
+            raise InvalidArgumentError("The HTTP method cannot be empty.")
+        if not (method.isascii() and method.isalpha() and method.isupper()):
+            raise InvalidArgumentError(
+                f'Invalid HTTP method "{method}", only uppercase letters are accepted.'
+            )
+
+    @staticmethod
+    def validate_auth(options: Mapping[str, object]) -> None:
+        """Refuse credentials this client cannot send, or two sets of them.
+
+        Raises:
+            InvalidArgumentError: When ``auth_basic`` or ``auth_bearer`` is
+                not of a shape credentials can be read from, or both are set.
+        """
+        basic = options.get("auth_basic")
+        if isinstance(basic, Sequence) and not isinstance(basic, str):
+            if len(basic) not in _AUTH_BASIC_PARTS:
+                raise InvalidArgumentError(
+                    f'Option "auth_basic" must contain 1 or 2 elements, "{len(basic)}" given.'
+                )
+        elif basic is not None and not isinstance(basic, str):
+            raise InvalidArgumentError(
+                f'Option "auth_basic" must be a string or a tuple, "{debug_type(basic)}" given.'
+            )
+
+        bearer = options.get("auth_bearer")
+        if bearer is not None:
+            HttpClientMixin._validate_bearer(bearer)
+        if basic is not None and bearer is not None:
+            raise InvalidArgumentError(
+                'Define either the "auth_basic" or the "auth_bearer" option, '
+                "setting both is not supported."
+            )
+
+    @staticmethod
+    def validate_body(options: Mapping[str, object]) -> None:
+        """Refuse a request that says what to send twice.
+
+        A JSON document and a body are both the whole body, so a request
+        carrying each has not said which one to send.
+
+        Raises:
+            InvalidArgumentError: When ``json`` and ``body`` are both set.
+        """
+        if options.get("json") is None:
+            return
+        if options.get("body") not in _NO_BODY:
+            raise InvalidArgumentError(
+                'Define either the "json" or the "body" option, setting both is not supported.'
+            )
+
+    @staticmethod
+    def _validate_bearer(bearer: object) -> None:
+        if not isinstance(bearer, str):
+            raise InvalidArgumentError(
+                f'Option "auth_bearer" must be a string, "{debug_type(bearer)}" given.'
+            )
+        if _UNPRINTABLE.search(bearer):
+            raise InvalidArgumentError(
+                f'Invalid character found in option "auth_bearer": {json.dumps(bearer)}.'
+            )

xtr_http_client/httpx_http_client.py

@@ -0,0 +1,327 @@
+"""The client that opens the connections and streams what comes back."""
+
+from __future__ import annotations
+
+import time
+from typing import TYPE_CHECKING, cast, final
+
+import anyio
+import httpx
+from typing_extensions import Unpack, override
+from xtr_http_client_contracts import HttpClientInterface
+from xtr_http_message import Request
+
+from .http_client_mixin import HttpClientMixin
+from .internal.httpx_clients import HttpxClients
+from .internal.httpx_errors import timed_out, transport_error
+from .internal.httpx_redirect import next_hop, same_origin
+from .internal.httpx_request import (
+    assemble_headers,
+    assemble_payload,
+    carries,
+    pin_host,
+    target_url,
+)
+from .response.httpx_response import to_http_response
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+    from types import TracebackType
+    from typing import Self
+
+    from xtr_http_client_contracts import RequestOptions
+    from xtr_http_message_contracts import RequestInterface
+
+    from .response import HttpResponse
+
+__all__ = ["HttpxHttpClient"]
+
+
+@final
+class HttpxHttpClient(HttpClientMixin, HttpClientInterface):
+    """Sends requests over real connections, and hands back answers as they arrive.
+
+    A request returns once the status line and the headers are in, whatever
+    the status; the body is read off the connection when the caller asks for
+    it, and the connection is held until the body is done with or the
+    response is left.
+
+    The request is authoritative and the options fill what it leaves out — a
+    header it already carries is the one sent, credentials apply only where it
+    has no ``Authorization`` of its own — which is what lets one set of
+    client-wide defaults sit under requests that each know their own mind.
+    What each part of an outgoing request is assembled from is in
+    :mod:`xtr_http_client.internal.httpx_request`; what is here is the
+    exchange, and the redirect chain it may turn into.
+
+    Connections are pooled by how they connect rather than by host: a proxy,
+    a trust store, a protocol version and the deadlines all decide what a
+    connection is, so each combination of them gets a pool, and
+    ``max_host_connections`` is each pool's ceiling across every host it
+    reaches.
+
+    ```python
+    async with HttpxHttpClient(max_host_connections=4) as client:
+        response = await client.request("GET", "https://example.com/orders")
+        orders = await response.to_array()
+    ```
+
+    Redirects are followed here rather than by the backend, so that an
+    ``Authorization`` header is dropped the moment a chain leaves the host it
+    was meant for, and comes back only when the chain returns to it.
+    """
+
+    __slots__ = ("_clients",)
+
+    def __init__(
+        self,
+        default_options: RequestOptions | None = None,
+        max_host_connections: int = 6,
+    ) -> None:
+        """Start from ``default_options``, opening nothing until a request is made.
+
+        Args:
+            default_options: What every request this client makes starts
+                from, over the contract's own defaults.
+            max_host_connections: How many connections one pool may hold at
+                once.
+
+        Raises:
+            InvalidArgumentError: When a default option is not one this
+                client knows.
+        """
+        super().__init__(default_options)
+        self._clients = HttpxClients(max_host_connections)
+
+    @override
+    async def request(
+        self,
+        method: str,
+        url: str,
+        **options: Unpack[RequestOptions],
+    ) -> HttpResponse:
+        """Make a request for ``method`` and ``url``, and return once its head is in.
+
+        Args:
+            method: The HTTP method, in upper case.
+            url: The URL to request, absolute or relative to ``base_uri``.
+            **options: How the request is to be made.
+
+        Returns:
+            The response, with its status and headers already in.
+
+        Raises:
+            TransportTimeoutError: When no answer came in time.
+            InvalidArgumentError: For an invalid method, URL or option.
+            TransportError: When no answer came.
+        """
+        self.validate_method(method)
+
+        return await self.send_request(Request(method, _reachable(url)), **options)
+
+    @override
+    async def send_request(
+        self,
+        request: RequestInterface,
+        **options: Unpack[RequestOptions],
+    ) -> HttpResponse:
+        """Send ``request``, the options filling what it leaves out.
+
+        Args:
+            request: The request to send.
+            **options: What the request leaves out.
+
+        Returns:
+            The response, with its status and headers already in.
+
+        Raises:
+            TransportTimeoutError: When no answer came in time.
+            InvalidArgumentError: For an invalid method, URL or option, and
+                for a body given both with the request and as an option.
+            TransportError: When no answer came.
+        """
+        self.validate_options(options)
+        self.validate_method(request.get_method())
+        merged = self.merge_default_options(options, self._default_options)
+        self.validate_auth(merged)
+        self.validate_body(merged)
+
+        client, resolved = self._clients.for_options(merged)
+        headers = assemble_headers(request, merged)
+        payload = await assemble_payload(request, merged, headers)
+        url, extensions = pin_host(target_url(request, merged), merged, resolved, headers)
+
+        outgoing = client.build_request(
+            request.get_method(),
+            url,
+            content=payload.content,
+            data=payload.form,
+            json=payload.document,
+            headers=headers,
+            extensions=extensions,
+        )
+
+        return await self._send(client, outgoing, merged, headers)
+
+    async def aclose(self) -> None:
+        """Close every pool, and with it every connection this client holds."""
+        await self._clients.aclose()
+
+    async def __aenter__(self) -> Self:
+        """Enter a block that owns this client's connections.
+
+        Returns:
+            This client.
+        """
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        """Close every connection however the block ends.
+
+        Args:
+            exc_type: The class of the exception the block is leaving with.
+            exc: That exception.
+            traceback: Its traceback.
+        """
+        del exc_type, exc, traceback
+        await self.aclose()
+
+    async def _send(
+        self,
+        client: httpx.AsyncClient,
+        outgoing: httpx.Request,
+        options: Mapping[str, object],
+        headers: Sequence[tuple[str, str]],
+    ) -> HttpResponse:
+        """Make the exchange, under whatever deadline the whole request was given."""
+        url = str(outgoing.url)
+        limit = _seconds(options.get("max_duration"))
+        start_time = time.time()
+        deadline = None if limit is None else anyio.current_time() + limit
+
+        try:
+            with anyio.fail_after(limit):
+                response, history = await _exchange(
+                    client,
+                    outgoing,
+                    _basic_credentials(options, headers),
+                    _hops(options.get("max_redirects")),
+                )
+        except TimeoutError as error:
+            raise timed_out(url) from error
+        except (httpx.HTTPError, httpx.InvalidURL) as error:
+            raise transport_error(error, url) from error
+
+        return await to_http_response(
+            response,
+            history,
+            response.request.method,
+            start_time,
+            options.get("user_data"),
+            deadline=deadline,
+            decode=not carries(headers, "accept-encoding"),
+        )
+
+
+async def _exchange(
+    client: httpx.AsyncClient,
+    outgoing: httpx.Request,
+    auth: tuple[str, str] | None,
+    max_redirects: int,
+) -> tuple[httpx.Response, list[httpx.Response]]:
+    """Send, then follow where each answer points until one points nowhere.
+
+    Following is done here, a hop at a time, for the one thing the backend
+    cannot be told: credentials belong to the host they were meant for, so an
+    ``Authorization`` the backend dropped on the way out of that host is put
+    back the moment the chain returns to it, and nowhere else.
+    """
+    response = await client.send(outgoing, auth=auth, stream=True, follow_redirects=False)
+    history: list[httpx.Response] = []
+    origin = response.request.url
+    authorization = cast("str | None", response.request.headers.get("authorization"))
+
+    while len(history) < max_redirects:
+        following = next_hop(response)
+        if following is None:
+            break
+
+        if (
+            authorization is not None
+            and "authorization" not in following.headers
+            and same_origin(following.url, origin)
+        ):
+            following.headers["Authorization"] = authorization
+
+        history.append(response)
+        await response.aclose()
+        response = await client.send(following, stream=True, follow_redirects=False)
+
+    return response, history
+
+
+def _reachable(url: str) -> str:
+    """``url`` with every part of it written in the form that reaches it.
+
+    A host named in another script is looked up in its ``xn--`` form, which
+    is also the only form a message request will hold, so the conversion
+    happens here — while the URL is still text — rather than further in,
+    where it would surface as a URL nobody can parse.
+
+    Raises:
+        InvalidArgumentError: When the URL cannot be read at all.
+    """
+    if url.isascii():
+        return url
+
+    try:
+        parsed = httpx.URL(url)
+
+        return str(parsed.copy_with(host=parsed.raw_host.decode("ascii")))
+    except (httpx.InvalidURL, UnicodeError) as error:
+        raise transport_error(httpx.InvalidURL(str(error)), url) from error
+
+
+def _basic_credentials(
+    options: Mapping[str, object],
+    headers: Sequence[tuple[str, str]],
+) -> tuple[str, str] | None:
+    """The user and password to authenticate with, when the request has no say.
+
+    Credentials written into the URL are left where they are: the backend
+    reads them off it, which is also what keeps them out of a redirect that
+    leaves the host.
+    """
+    basic = options.get("auth_basic")
+    if basic is None or carries(headers, "authorization"):
+        return None
+
+    if isinstance(basic, str):
+        user, _, password = basic.partition(":")
+
+        return user, password
+
+    parts = [str(part) for part in cast("Sequence[object]", basic)]
+
+    return parts[0], parts[1] if len(parts) > 1 else ""
+
+
+def _seconds(value: object) -> float | None:
+    """A limit in seconds, or ``None`` when zero said there is none."""
+    if isinstance(value, (int, float)) and value > 0:
+        return float(value)
+
+    return None
+
+
+def _hops(value: object) -> int:
+    """How many redirects may be followed; zero or less follows none."""
+    if isinstance(value, int):
+        return max(0, value)
+
+    return 0

xtr_http_client/internal/__init__.py

@@ -0,0 +1,13 @@
+"""What the clients of this package share, and nobody outside it should import.
+
+The option handling a client does before a connection is opened — merging a
+request's options over the client's defaults and refusing a name no client
+knows — reaches callers through
+:class:`HttpClientMixin <xtr_http_client.http_client_mixin.HttpClientMixin>`,
+which is the one supported way in. These modules are where it is written; they
+move without notice.
+"""
+
+from __future__ import annotations
+
+__all__: list[str] = []

xtr_http_client/internal/debug_type.py

@@ -0,0 +1,14 @@
+"""How a value is named in the message that refuses it."""
+
+from __future__ import annotations
+
+__all__ = ["debug_type"]
+
+
+def debug_type(value: object) -> str:
+    """Name the type of ``value`` the way an error message should.
+
+    ``None`` is named ``null`` because that is what a caller wrote, or what a
+    JSON document carried; everything else is named by its class.
+    """
+    return "null" if value is None else type(value).__name__

xtr_http_client/internal/httpx_body.py

@@ -0,0 +1,88 @@
+"""The pieces of a response body, as they come off the backend transfer."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+import anyio
+import httpx
+
+from .httpx_errors import timed_out, transport_error
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+    from typing import Self
+
+__all__ = ["HttpxBody"]
+
+
+@final
+class HttpxBody:
+    """The backend's body, with the two things a response body of this package needs.
+
+    A deadline for the whole request covers the body as well as the head, and
+    the body is read long after the request was made — wherever the caller
+    asked for it — so the deadline has to travel with the body rather than
+    stay where the request was. It is checked on every piece.
+
+    And a transfer that breaks half way raises the backend's own error, which
+    a caller holding the client interface has never heard of. Translating it
+    here means every piece passes one place where that cannot escape.
+    """
+
+    __slots__ = ("_deadline", "_pieces", "_response", "_url")
+
+    def __init__(
+        self,
+        response: httpx.Response,
+        pieces: AsyncIterator[bytes],
+        deadline: float | None = None,
+    ) -> None:
+        """Hold the transfer the body comes out of.
+
+        Args:
+            response: The transfer, which closing the body lets go of.
+            pieces: The body, piece by piece, as the backend produces it.
+            deadline: When the whole request runs out of time, on anyio's
+                clock. ``None`` is no limit, which is what ``max_duration``
+                of zero means.
+        """
+        self._response = response
+        self._pieces = pieces
+        self._deadline = deadline
+        self._url = str(response.url)
+
+    def __aiter__(self) -> Self:
+        """Return this iterator, which is the body itself."""
+        return self
+
+    async def __anext__(self) -> bytes:
+        """Return the next piece of the body, waiting for it to arrive.
+
+        Returns:
+            The piece, which may be of any size the transfer arrived in.
+
+        Raises:
+            StopAsyncIteration: Once the whole body has arrived.
+            TransportTimeoutError: When the request ran out of time.
+            TransportError: When the transfer broke.
+        """
+        try:
+            with anyio.fail_after(self._remaining()):
+                return await self._pieces.__anext__()
+        except StopAsyncIteration:
+            raise
+        except TimeoutError as error:
+            raise timed_out(self._url) from error
+        except (httpx.HTTPError, httpx.InvalidURL) as error:
+            raise transport_error(error, self._url) from error
+
+    async def aclose(self) -> None:
+        """Let go of the transfer, which frees the connection it was holding."""
+        await self._response.aclose()
+
+    def _remaining(self) -> float | None:
+        """How long the request has left, or ``None`` when it was given no limit."""
+        if self._deadline is None:
+            return None
+        return self._deadline - anyio.current_time()