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

xtr_http_client_contracts/options_defaults.py

@@ -0,0 +1,69 @@
+"""What a request asks for when nobody asked for anything in particular."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    from .request_options import RequestOptions
+
+__all__ = ["OPTIONS_DEFAULTS"]
+
+OPTIONS_DEFAULTS: Final[RequestOptions] = {
+    # No credentials are sent unless the caller asks for them.
+    "auth_basic": None,
+    "auth_bearer": None,
+    # Nothing is added to the URL, nothing is sent alongside it.
+    "query": {},
+    "headers": {},
+    "body": b"",
+    "json": None,
+    # Carried for the caller, never read.
+    "user_data": None,
+    # Enough hops for any sane chain, few enough to end a loop.
+    "max_redirects": 20,
+    # The best version the connection offers.
+    "http_version": None,
+    # Every URL is absolute until a caller says otherwise.
+    "base_uri": None,
+    # 60 seconds: long enough for a slow server, short enough to free the
+    # connection.
+    "timeout": None,
+    # Neither the transfer as a whole nor connecting is time limited: the
+    # idle timeout already ends a transfer nothing is coming in on.
+    "max_duration": 0.0,
+    "max_connect_duration": 0.0,
+    # Hosts are resolved the usual way, and reached without a proxy.
+    "resolve": {},
+    "proxy": None,
+    # A certificate is checked, and checked against the host asked for.
+    # Turning either off is a decision an application makes in the open.
+    "verify_peer": True,
+    "verify_host": True,
+    # The trust store and the client certificate are whatever the platform
+    # offers.
+    "cafile": None,
+    "capath": None,
+    "local_cert": None,
+    "local_pk": None,
+    "passphrase": None,
+    # How often a client that retries tries again.
+    "max_retries": 3,
+    # Additional options a client may ignore when it does not support them,
+    # unlike the regular options it must refuse; `use_persistent_connections`
+    # says whether to use persistent connections where supported.
+    "extra": {"use_persistent_connections": False},
+}
+"""Every option the contract names, mapped to what it means to leave it out.
+
+A client merges what a request was given over its own defaults, and those
+over this, so every option always has a value by the time a request is made.
+Nothing here is an instruction — it is the absence of one, which is why the
+defaults name no host, no credentials and no deadline.
+
+The entries worth reading twice: ``timeout`` of ``None`` is not "no timeout"
+but 60 seconds; ``max_duration`` and ``max_connect_duration`` of zero *are*
+"no limit".
+
+The mapping is shared, so merge into a copy rather than writing to it.
+"""

xtr_http_client_contracts/request_options.py

@@ -0,0 +1,106 @@
+"""Everything a request can be asked to do, as one typed mapping."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, TypedDict
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterable, Mapping, Sequence
+
+__all__ = ["RequestOptions"]
+
+
+class RequestOptions(TypedDict, total=False):
+    """How a request is to be made, beyond its method and URL.
+
+    Every option is optional, and an option left out is one nobody asked
+    about: the client fills it in from its own defaults, which start at
+    :data:`OPTIONS_DEFAULTS
+    <xtr_http_client_contracts.options_defaults.OPTIONS_DEFAULTS>`. The same
+    keys are what :meth:`HttpClientInterface.with_options
+    <xtr_http_client_contracts.http_client_interface.HttpClientInterface.with_options>`
+    takes, where they become the defaults of the client it returns.
+
+    A name not listed here is refused. ``extra`` carries what one client
+    understands and another has no use for, so entries in it may be ignored.
+
+    Attributes:
+        auth_basic: Credentials for basic authentication: ``"user:password"``,
+            or the user alone, or the two as a tuple. ``None`` sends none.
+        auth_bearer: A token to send as a bearer credential. ``None`` sends
+            none.
+        query: Parameters to merge into the URL's query string. A scalar is one
+            value; a sequence repeats the name once per item. ``None``, booleans
+            and nested mappings are not accepted. They win over a parameter of
+            the same name already in the URL.
+        headers: Headers to send, a mapping of name to one value or several.
+        body: What to send as the request body. Bytes or text go as they are;
+            a mapping is sent as an HTML form; an async iterable of bytes is
+            sent as it is produced, which is how a body too large to hold is
+            uploaded.
+        json: A value to send as a JSON body. The client encodes it and sets
+            a JSON content type unless ``headers`` already names one. Setting
+            both this and ``body`` is refused.
+        user_data: Anything the caller wants to find again on the response,
+            under the ``user_data`` entry of ``get_info()``. Never read by
+            the client.
+        max_redirects: How many redirects to follow. Zero or less follows
+            none, which leaves the 3xx to be answered with.
+        http_version: The HTTP version to ask for — ``"1.0"``, ``"1.1"``,
+            ``"2"`` or ``"2.0"``. ``None`` leaves the client to use the best
+            version the connection offers.
+        base_uri: The URI a relative URL is resolved against. A sequence of
+            them is only for a client that retries, which moves along it from
+            one attempt to the next.
+        timeout: How long the transfer may go quiet for, in seconds. ``None``
+            is 60 seconds.
+        max_duration: How long the whole request and response may take, in
+            seconds. Zero is unlimited.
+        max_connect_duration: How long resolving, connecting and the TLS
+            handshake may take, in seconds. Zero is unlimited.
+        resolve: Host to IP address, used instead of asking a resolver. This
+            is what pins a request to an address that has already been
+            checked, so that nothing can change under it between the check
+            and the connection.
+        proxy: The proxy to go through, as a URL.
+        verify_peer: Whether to check that the peer's certificate is trusted.
+        verify_host: Whether to check that the certificate is for the host
+            being asked for.
+        cafile: A file of certificates to trust instead of the defaults.
+        capath: A directory of certificates to trust instead of the defaults.
+        local_cert: A client certificate to present.
+        local_pk: The private key of ``local_cert``, when it is kept apart.
+        passphrase: The passphrase of ``local_pk``.
+        max_retries: How many times a client that retries may try the request
+            again. A client that does not retry ignores it.
+        extra: Additional options a client may ignore when it does not
+            support them, unlike the regular options it must refuse:
+            ``use_persistent_connections`` says whether to use persistent
+            connections where supported, ``trace_content`` whether a tracing
+            client keeps the bodies.
+    """
+
+    auth_basic: str | tuple[str] | tuple[str, str] | None
+    auth_bearer: str | None
+    query: Mapping[str, str | int | float | Sequence[str | int | float]]
+    headers: Mapping[str, str | Sequence[str]]
+    body: bytes | str | Mapping[str, object] | AsyncIterable[bytes]
+    json: object
+    user_data: object
+    max_redirects: int
+    http_version: str | None
+    base_uri: str | Sequence[str] | None
+    timeout: float | None
+    max_duration: float
+    max_connect_duration: float
+    resolve: Mapping[str, str]
+    proxy: str | None
+    verify_peer: bool
+    verify_host: bool
+    cafile: str | None
+    capath: str | None
+    local_cert: str | None
+    local_pk: str | None
+    passphrase: str | None
+    max_retries: int
+    extra: Mapping[str, object]

xtr_http_client_contracts/testing/__init__.py

@@ -0,0 +1,12 @@
+"""What an implementation of the client contract tests itself with.
+
+Install it with the ``testing`` extra. Nothing here is imported by the contract itself, so an
+application that only depends on the interfaces never pays for it.
+"""
+
+from __future__ import annotations
+
+from .http_client_test_case import HttpClientTestCase
+from .test_http_server import TestHttpServer
+
+__all__ = ["HttpClientTestCase", "TestHttpServer"]

xtr_http_client_contracts/testing/_fixture_request.py

@@ -0,0 +1,184 @@
+"""One request the fixture server read, and the variables its echo routes answer with.
+
+The echo routes answer a JSON object describing the request they received, so a client test can
+assert on what actually arrived. The names in that object are:
+
+======================  ====================================================================
+``SERVER_PROTOCOL``     the protocol token the request came in with, e.g. ``HTTP/1.1``
+``SERVER_NAME``         the host the server is bound to, not the one the request asked for
+``REQUEST_URI``         the raw request target, absolute-form and query string included
+``REQUEST_METHOD``      the method, as sent
+``AUTH_USER``           the user of the request's Basic credentials, when it carried any
+``AUTH_PW``             their password, split off at the first colon
+``REMOTE_ADDR``         the address the connection came from
+``REMOTE_PORT``         its port, as a string
+``HTTP_<NAME>``         every request header, upper-cased, dashes turned into underscores
+======================  ====================================================================
+
+The order is the one above: the fixed names first, then the headers as they arrived. A header
+sent more than once is answered once, its values joined with ``", "``. ``AUTH_USER`` and
+``AUTH_PW`` appear only when the request carried credentials this module could decode — the
+fixture these routes answer like exposed the same two values under names belonging to its own
+runtime, which would mean nothing here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from base64 import b64decode
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, final
+from urllib.parse import urlsplit
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+__all__ = ["FixtureRequest", "read_request"]
+
+_REQUEST_LINE_PARTS = 3
+_BASIC = "basic"
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class FixtureRequest:
+    """What arrived on one connection, parsed no further than the routes need."""
+
+    method: str
+    target: str
+    protocol: str
+    headers: tuple[tuple[str, str], ...]
+    body: bytes
+    peer: tuple[str, str]
+    server_name: str
+    server_port: int
+
+    @property
+    def path(self) -> str:
+        """The target's path, which is what the routes dispatch on.
+
+        An absolute target — what a client sends through a proxy — routes on its path too, so
+        ``http://localhost:<port>/301/proxy`` reaches the same route as ``/301/proxy``.
+        """
+        return urlsplit(self.target).path
+
+    @property
+    def query(self) -> str:
+        """The target's query string, undecoded."""
+        return urlsplit(self.target).query
+
+    def header(self, name: str) -> str | None:
+        """The named header, repeats joined, or ``None`` when it was not sent."""
+        return _joined(self.headers, name)
+
+    def credentials(self) -> tuple[str, str] | None:
+        """The Basic user and password the request carried, or ``None``.
+
+        Anything that is not a decodable ``Basic`` token holding a colon counts as no
+        credentials at all, which is how a client sending a bearer token reaches a route that
+        only looks for Basic.
+        """
+        authorization = self.header("authorization")
+        if authorization is None:
+            return None
+        scheme, _, token = authorization.partition(" ")
+        if scheme.lower() != _BASIC:
+            return None
+        try:
+            decoded = b64decode(token, validate=True).decode()
+        except ValueError:
+            return None
+        user, separator, password = decoded.partition(":")
+        return (user, password) if separator else None
+
+    def variables(self) -> dict[str, str]:
+        """The object the echo routes answer with, in the order described for this module."""
+        variables = {
+            "SERVER_PROTOCOL": self.protocol,
+            "SERVER_NAME": self.server_name,
+            "REQUEST_URI": self.target,
+            "REQUEST_METHOD": self.method,
+        }
+        credentials = self.credentials()
+        if credentials is not None:
+            variables["AUTH_USER"], variables["AUTH_PW"] = credentials
+        variables["REMOTE_ADDR"] = self.peer[0]
+        variables["REMOTE_PORT"] = self.peer[1]
+        for name, _ in self.headers:
+            key = "HTTP_" + name.upper().replace("-", "_")
+            variables[key] = _joined(self.headers, name) or ""
+        return variables
+
+
+async def read_request(
+    reader: asyncio.StreamReader,
+    writer: asyncio.StreamWriter,
+    server_name: str,
+) -> FixtureRequest | None:
+    """Read one request, or answer ``None`` for anything that is not one.
+
+    A connection that says nothing, or opens with something that is not a request line, gets
+    no answer at all: a client probing the port should see it closed, not a protocol error.
+    """
+    try:
+        head = await reader.readuntil(b"\r\n\r\n")
+    except (asyncio.IncompleteReadError, asyncio.LimitOverrunError):
+        return None
+    lines = head.decode("latin-1").split("\r\n")
+    parts = lines[0].split(" ")
+    if len(parts) != _REQUEST_LINE_PARTS or not parts[2].startswith("HTTP/"):
+        return None
+    method, target, protocol = parts
+    headers = tuple(
+        (name.strip(), value.strip())
+        for name, separator, value in (line.partition(":") for line in lines[1:] if line)
+        if separator
+    )
+    return FixtureRequest(
+        method=method,
+        target=target,
+        protocol=protocol,
+        headers=headers,
+        body=await _read_body(reader, headers),
+        peer=_peer(writer),
+        server_name=server_name,
+        server_port=_local_port(writer),
+    )
+
+
+def _joined(headers: Sequence[tuple[str, str]], name: str) -> str | None:
+    wanted = name.lower()
+    values = [value for key, value in headers if key.lower() == wanted]
+    return ", ".join(values) if values else None
+
+
+def _peer(writer: asyncio.StreamWriter) -> tuple[str, str]:
+    """The address and port the connection came from, as text, which is how they are echoed."""
+    address: tuple[object, ...] = writer.get_extra_info("peername")
+    return str(address[0]), str(address[1])
+
+
+def _local_port(writer: asyncio.StreamWriter) -> int:
+    """The port the connection reached, which a redirect back to this server must name."""
+    address: tuple[object, ...] = writer.get_extra_info("sockname")
+    return int(str(address[1]))
+
+
+async def _read_body(reader: asyncio.StreamReader, headers: Sequence[tuple[str, str]]) -> bytes:
+    transfer_encoding = _joined(headers, "transfer-encoding") or ""
+    if "chunked" in transfer_encoding.lower():
+        return await _read_chunks(reader)
+    declared = _joined(headers, "content-length")
+    length = int(declared) if declared is not None and declared.isdigit() else 0
+    return await reader.readexactly(length) if length else b""
+
+
+async def _read_chunks(reader: asyncio.StreamReader) -> bytes:
+    body = bytearray()
+    while True:
+        size = int((await reader.readline()).strip() or b"0", 16)
+        if size == 0:
+            _ = await reader.readline()
+            return bytes(body)
+        body += await reader.readexactly(size)
+        _ = await reader.readline()

xtr_http_client_contracts/testing/_fixture_response.py

@@ -0,0 +1,80 @@
+"""How the fixture server puts a response on the wire.
+
+Responses are assembled as bytes rather than by a server framework: several routes answer
+something deliberately malformed — a length that does not match the body, a declared encoding
+the body does not use, framing that stops mid-chunk — and no framework would emit those.
+
+Every response answers in the protocol its request came in with and closes the connection, so
+a client never has to guess where a body that declares no length ends.
+"""
+
+from __future__ import annotations
+
+import gzip
+import json
+from dataclasses import dataclass
+from http import HTTPStatus
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from asyncio import StreamWriter
+    from collections.abc import Mapping
+
+    from ._fixture_request import FixtureRequest
+
+__all__ = ["Answer", "compact", "compressed", "head", "length", "pretty", "send"]
+
+_PHRASES = {status.value: status.phrase for status in HTTPStatus}
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class Answer:
+    """A status and the headers to answer with; the body follows them."""
+
+    status: int
+    headers: tuple[tuple[str, str], ...] = ()
+
+
+def head(request: FixtureRequest, answer: Answer) -> bytes:
+    """The status line and headers, ending with the blank line that opens the body."""
+    phrase = _PHRASES.get(answer.status, "Unknown")
+    lines = [f"{request.protocol} {answer.status} {phrase}"]
+    lines += [f"{name}: {value}" for name, value in answer.headers]
+    lines.append("Connection: close")
+    return ("\r\n".join(lines) + "\r\n\r\n").encode("latin-1")
+
+
+async def send(writer: StreamWriter, *parts: bytes) -> None:
+    """Write, and wait for it to leave: a client that hung up ends the route here."""
+    writer.write(b"".join(parts))
+    await writer.drain()
+
+
+def pretty(payload: Mapping[str, object]) -> bytes:
+    """JSON indented as the echo routes answer it."""
+    return json.dumps(payload, indent=4, ensure_ascii=False).encode()
+
+
+def compact(payload: Mapping[str, object]) -> str:
+    """JSON with no spacing, for the payloads that travel in a header."""
+    return json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
+
+
+def length(body: bytes) -> tuple[str, str]:
+    """The header declaring ``body``'s real length."""
+    return ("Content-Length", str(len(body)))
+
+
+def compressed(
+    request: FixtureRequest,
+    payload: bytes,
+) -> tuple[bytes, tuple[tuple[str, str], ...]]:
+    """``payload`` gzipped and the headers saying so, when the request asked for gzip.
+
+    A request that did not ask gets the payload as it is, and no headers: a client must be
+    able to drive the same route both ways.
+    """
+    if "gzip" not in (request.header("accept-encoding") or ""):
+        return payload, ()
+    return gzip.compress(payload), (("Content-Encoding", "gzip"), ("Vary", "Accept-Encoding"))