headgate 0.2.0__py3-none-any.whl

headgate/_core/_retry_after.py

@@ -0,0 +1,76 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""How long a response asks its client to wait: ``Retry-After`` (RFC 9110 section 10.2.3) and ``retry-after-ms``.
+
+Two layers act on the same answer, so it is read in one place: the retry layer waits it before re-sending, and the rate
+budget pauses every sender sharing it until it has passed. Reading it the same way is what makes the two waits one.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+import time
+from datetime import UTC
+from email.utils import parsedate_to_datetime
+from typing import TYPE_CHECKING, Final
+
+if TYPE_CHECKING:
+    import httpx2
+
+__all__ = ["RETRY_AFTER_STATUSES", "parse_retry_after", "retry_after_of"]
+
+#: The statuses a ``Retry-After`` means something on: rate limited (RFC 6585) and unavailable (RFC 9110).
+RETRY_AFTER_STATUSES: Final = frozenset({429, 503})
+
+#: A non-negative decimal number of seconds: ``Retry-After`` defines whole seconds, and fractions are accepted too.
+_DECIMAL: Final = re.compile(r"\d+(?:\.\d+)?")
+
+#: Milliseconds in a second, for ``retry-after-ms``.
+_MS_PER_SECOND: Final = 1000.0
+
+#: What ``parsedate_to_datetime`` raises for a value it cannot parse.
+_DATE_ERRORS: Final = (TypeError, ValueError)
+
+
+def _decimal_seconds(value: str) -> float | None:
+    """Return *value* as a finite non-negative number, or ``None`` when it is not a plain ASCII decimal."""
+    if not (value.isascii() and _DECIMAL.fullmatch(value)):
+        return None
+    seconds = float(value)
+    return seconds if math.isfinite(seconds) else None
+
+
+def parse_retry_after(value: str, *, now: float) -> float | None:
+    """Return a ``Retry-After`` value as seconds from *now* (a Unix time); ``None`` when it is in neither form.
+
+    Whole and fractional seconds are read as they are. An HTTP-date is measured from *now*: a zone-less one is read as
+    GMT, which an HTTP-date always is, and a past one is no wait at all.
+    """
+    value = value.strip()
+    seconds = _decimal_seconds(value)
+    if seconds is not None:
+        return seconds
+    try:
+        when = parsedate_to_datetime(value)
+    except _DATE_ERRORS:
+        return None
+    if when.tzinfo is None:
+        when = when.replace(tzinfo=UTC)
+    return max(0.0, when.timestamp() - now)
+
+
+def retry_after_of(response: httpx2.Response, *, now: float | None = None) -> float | None:
+    """Return the seconds a 429 or 503 *response* asks to wait: ``retry-after-ms`` if it parses, else ``Retry-After``.
+
+    ``None`` for any other status, which RFC 9110 and RFC 6585 give the header no meaning on, and when neither header
+    is present or parses. *now* is the Unix time an HTTP-date is measured from, the system's wall clock by default.
+    """
+    if response.status_code not in RETRY_AFTER_STATUSES:
+        return None
+    millis = _decimal_seconds(response.headers.get("retry-after-ms", "").strip())
+    if millis is not None:
+        return millis / _MS_PER_SECOND
+    header = response.headers.get("retry-after")
+    return None if header is None else parse_retry_after(header, now=time.time() if now is None else now)

headgate/_core/_seams.py

@@ -0,0 +1,50 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""Seams two policy areas meet at, defined once so neither has to import the other.
+
+* :class:`CredentialStamper`: what an auth declares about the credentials it puts on a request. The credential guard
+  uses it to keep them on trusted origins; the cache uses it to partition entries by credential and to keep
+  credentials out of storage. Its first two members, :class:`CredentialCarrier`, are what a signing middleware
+  declares, for the guard alone.
+* :data:`BREAKER_GATE`: set by the client on every call, read by the retry layer, so a retry sequence stops as soon as
+  the origin's breaker opens without the retry layer knowing about breakers.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Protocol, runtime_checkable
+
+from headgate._core._context import Slot
+
+__all__ = ["BREAKER_GATE", "CredentialCarrier", "CredentialStamper"]
+
+
+@runtime_checkable
+class CredentialCarrier(Protocol):
+    """Something that declares the credentials it puts on a request: an auth, or a signing middleware."""
+
+    @property
+    def credential_headers(self) -> frozenset[str]:
+        """Return the names of the headers it sets (compared case-insensitively)."""
+        ...
+
+    @property
+    def credential_params(self) -> frozenset[str]:
+        """Return the names of the query parameters it sets."""
+        ...
+
+
+@runtime_checkable
+class CredentialStamper(CredentialCarrier, Protocol):
+    """An auth that declares the credentials it stamps on a request, and names the credential they stand for."""
+
+    def credential_identity(self) -> bytes:
+        """Return stable bytes identifying the credential (its secret material); never stored, only hashed."""
+        ...
+
+
+#: Answers whether the breaker for the call's origin is refusing right now. The client puts it on every call's
+#: context; the retry layer checks it before scheduling another attempt.
+BREAKER_GATE = Slot[Callable[[], bool]]("breaker_gate")

headgate/_core/_switch.py

@@ -0,0 +1,40 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""The construction-time switch that builds clients with their transport policy off.
+
+It lives here, below every layer, because a rate budget honours it when it is built, whoever builds it, and the
+policy subpackages may import only this core. :mod:`headgate.policy` is its public face and documents what "off" means.
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+__all__ = ["policy_disabled", "policy_is_disabled"]
+
+#: Task-local: is transport policy switched off for clients built right now?
+_POLICY_OFF: ContextVar[bool] = ContextVar("headgate_policy_off", default=False)
+
+
+@contextmanager
+def policy_disabled() -> Generator[None]:
+    """Build clients with retry, the circuit breaker, and rate limiting switched off.
+
+    Affects only clients constructed inside the block. Safe to nest.
+    """
+    token = _POLICY_OFF.set(True)
+    try:
+        yield
+    finally:
+        _POLICY_OFF.reset(token)
+
+
+def policy_is_disabled() -> bool:
+    """Return whether a client being constructed right now should skip its transport policy."""
+    return _POLICY_OFF.get()

headgate/_core/_time.py

@@ -0,0 +1,102 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""Time and randomness as parameters: the clock, the sleep and the random source every layer is handed.
+
+Each layer that waits, measures or draws takes the function it needs as a parameter with a production default, so a
+test drives time instead of waiting for it. The three shapes are protocols over plain callables, so ``time.monotonic``,
+``asyncio.sleep`` and ``random.random`` satisfy them as they are.
+
+``AsyncBaseClient`` reads the :class:`Timing` it hands its layers from :func:`current_timing` when it is built. A client
+class usually fixes its own options in ``super().__init__()`` and exposes none of them, so a test replaces the timing
+of the clients it builds with :func:`timing_override` instead of reaching into each one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import random
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Generator
+
+__all__ = [
+    "SYSTEM_TIMING",
+    "Clock",
+    "RandomSource",
+    "Sleep",
+    "Timing",
+    "asyncio_sleep",
+    "current_timing",
+    "system_random",
+    "timing_override",
+]
+
+
+class Clock(Protocol):
+    """Return monotonic seconds: only differences between two readings mean anything."""
+
+    def __call__(self) -> float:
+        """Return the current reading."""
+        ...
+
+
+class Sleep(Protocol):
+    """Wait *seconds* without blocking the event loop."""
+
+    def __call__(self, seconds: float, /) -> Awaitable[None]:
+        """Return an awaitable that completes after *seconds*."""
+        ...
+
+
+class RandomSource(Protocol):
+    """Return a uniform draw in ``[0, 1)``."""
+
+    def __call__(self) -> float:
+        """Return the next draw."""
+        ...
+
+
+async def asyncio_sleep(seconds: float, /) -> None:
+    """Sleep through ``asyncio.sleep``, looked up on every call so a process-wide patch of it still applies."""
+    await asyncio.sleep(seconds)
+
+
+#: The operating system's generator, not the ``random`` module's shared one: an application that seeds ``random`` (for
+#: reproducible tests, say) would otherwise give every process it runs the same jitter, which exists to spread them.
+system_random: RandomSource = random.SystemRandom().random
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Timing:
+    """The clock and the sleep a client hands every layer it builds."""
+
+    clock: Clock = field(default=time.monotonic)
+    sleep: Sleep = field(default=asyncio_sleep)
+
+
+#: Production timing: ``time.monotonic`` and ``asyncio.sleep``.
+SYSTEM_TIMING = Timing()
+
+#: The timing clients built in this context take. A ``ContextVar`` so concurrent tasks cannot see each other's override.
+_TIMING: ContextVar[Timing] = ContextVar("headgate_timing", default=SYSTEM_TIMING)
+
+
+def current_timing() -> Timing:
+    """Return the timing a client constructed right now takes."""
+    return _TIMING.get()
+
+
+@contextmanager
+def timing_override(timing: Timing) -> Generator[None]:
+    """Build clients with *timing* instead of :data:`SYSTEM_TIMING`; only clients constructed inside the block."""
+    token = _TIMING.set(timing)
+    try:
+        yield
+    finally:
+        _TIMING.reset(token)

headgate/_curl.py

@@ -0,0 +1,287 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+#
+# This file is derived from httpx-curl-cffi 0.1.5 (https://github.com/vgavro/httpx-curl-cffi), under its license:
+#
+# BSD 3-Clause License
+#
+# Copyright (c) 2025, Victor Gavro
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice, this
+#    list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+#    this list of conditions and the following disclaimer in the documentation
+#    and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its
+#    contributors may be used to endorse or promote products derived from
+#    this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+"""The ``curl_cffi`` transport for hosts fronted by TLS-fingerprinting CDNs (the ``headgate[curl]`` extra).
+
+Vendored from ``httpx-curl-cffi`` 0.1.5 (BSD-3-Clause, Copyright (c) 2025 Victor Gavro; the licence is the comment block
+above, as clause 1 requires) and cut down to what headgate calls. The upstream package speaks plain ``httpx``; this copy
+speaks ``httpx2``. ``curl_cffi`` itself ships no httpx or httpx2 transport.
+
+The kept surface is ``impersonate``, ``default_headers``, ``curl_options`` and ``max_connections``. The sync transport,
+the fingerprint and proxy parameter bag and the shims for ``curl_cffi`` older than the declared floor are not kept.
+
+The transport behaves like a native httpx2 one wherever the layers above it can tell:
+
+* curl ignores the environment's proxy (``NOPROXY="*"``), keeps no cookie and follows no redirect, so the stack above
+  it (redirect handling, the breaker, retry) sees every hop and every status.
+* curl decompresses the body itself and exposes no raw one (``curl_cffi`` issue 438). The response therefore carries no
+  ``Content-Encoding`` or ``Content-Length``: its stream already holds the decoded bytes, so httpx2 picks its identity
+  decoder and a cache that stores the stream replays it correctly. The headers as received stay on the ``curl_cffi``
+  response, in ``response.extensions["curl"]["response"]``.
+* ``default_headers=True`` hands the header set to curl's impersonation profile, so httpx2's own defaults
+  (``User-Agent: python-httpx2/...``, ``Accept-Encoding``, ...) and the ``User-Agent`` a client sends without
+  ``HttpOptions(user_agent=...)`` are removed from the request when the caller left them untouched.
+* A curl error code, raised while sending or while streaming the body, maps onto the httpx2 exception a native
+  transport would raise, so the policy layers classify it.
+* Closing a response before its body is read aborts the transfer. ``curl_cffi``'s own ``aclose`` waits for the whole
+  body to arrive into an unbounded queue, which would defeat headgate's response size cap.
+
+**The SSRF guard** (``HttpOptions(allow_private_hosts=False)``) vets every hop's host before this transport sends it,
+but cannot pin the connection to the address it vetted, because curl resolves the name itself. Pinning would take
+``CURLOPT_RESOLVE`` per request, and ``curl_cffi`` 0.16 sets libcurl options only session-wide, after the handle is
+taken from the pool (an ``await``, so a per-request value would race between concurrent requests), and a resolve entry
+stays in the multi handle's shared DNS cache after the transfer. Over this transport the guard therefore refuses a
+forbidden host, but a rebinding DNS answer between the check and curl's own lookup is not ruled out.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import functools
+from typing import TYPE_CHECKING, Any, get_args, override
+
+import httpx2
+
+from headgate._user_agent import DEFAULT_USER_AGENT
+
+try:
+    from curl_cffi import CurlECode, CurlHttpVersion, CurlOpt
+    from curl_cffi.requests.exceptions import RequestException as _RequestError
+    from curl_cffi.requests.session import AsyncSession as _AsyncSession
+    from curl_cffi.requests.session import HttpMethod
+except ImportError as exc:
+    msg = "AsyncCurlTransport needs the curl extra: pip install 'headgate[curl]'"
+    raise ImportError(msg) from exc
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Mapping
+
+    from curl_cffi.requests import Response as _Response
+    from curl_cffi.requests.impersonate import BrowserTypeLiteral
+
+__all__ = ["AsyncCurlTransport"]
+
+#: The httpx2 exception a native transport raises for the same failure. A code missing here becomes a plain
+#: :class:`httpx2.TransportError`; ``OPERATION_TIMEDOUT`` is split by :func:`_timeout_error`. ``READ_ERROR`` and
+#: ``WRITE_ERROR`` are absent on purpose: in libcurl they are local callback failures, not network ones
+#: (``WRITE_ERROR`` is what an aborted transfer reports).
+_CURL_ERRORS: dict[int, type[httpx2.TransportError | httpx2.DecodingError]] = {
+    CurlECode.UNSUPPORTED_PROTOCOL: httpx2.UnsupportedProtocol,
+    CurlECode.COULDNT_RESOLVE_PROXY: httpx2.ProxyError,
+    CurlECode.PROXY: httpx2.ProxyError,
+    CurlECode.COULDNT_RESOLVE_HOST: httpx2.ConnectError,
+    CurlECode.COULDNT_CONNECT: httpx2.ConnectError,
+    CurlECode.QUIC_CONNECT_ERROR: httpx2.ConnectError,
+    CurlECode.SSL_CONNECT_ERROR: httpx2.ConnectError,
+    CurlECode.PEER_FAILED_VERIFICATION: httpx2.ConnectError,
+    CurlECode.SEND_ERROR: httpx2.WriteError,
+    CurlECode.RECV_ERROR: httpx2.ReadError,
+    CurlECode.GOT_NOTHING: httpx2.RemoteProtocolError,
+    CurlECode.WEIRD_SERVER_REPLY: httpx2.RemoteProtocolError,
+    CurlECode.PARTIAL_FILE: httpx2.RemoteProtocolError,
+    CurlECode.HTTP2: httpx2.RemoteProtocolError,
+    CurlECode.HTTP2_STREAM: httpx2.RemoteProtocolError,
+    CurlECode.HTTP3: httpx2.RemoteProtocolError,
+    CurlECode.BAD_CONTENT_ENCODING: httpx2.DecodingError,
+}
+
+#: libcurl's messages for a timeout before the connection is up. Message text is the only signal: libcurl reports every
+#: timeout as ``OPERATION_TIMEDOUT``, and the failed handle is reset before the error reaches Python.
+_CONNECT_TIMEOUT_MESSAGES = ("Resolving timed out", "Connection timed out", "Failed to connect to")
+
+#: ``CURLINFO_HTTP_VERSION`` values, as httpx2's ``http_version`` extension spells them.
+_HTTP_VERSIONS: dict[int, bytes] = {
+    CurlHttpVersion.V1_0: b"HTTP/1.0",
+    CurlHttpVersion.V1_1: b"HTTP/1.1",
+    CurlHttpVersion.V2_0: b"HTTP/2",
+    CurlHttpVersion.V3: b"HTTP/3",
+}
+
+#: The response headers that describe the body as it was on the wire, which curl has already decoded.
+_WIRE_ENCODING_HEADERS = ("content-encoding", "content-length")
+
+_METHODS: dict[str, HttpMethod] = {method: method for method in get_args(HttpMethod)}
+
+
+class AsyncCurlTransport(httpx2.AsyncBaseTransport):
+    """Send each request through ``curl_cffi`` with a browser's TLS handshake, as an ``httpx2`` async transport.
+
+    :param impersonate: the ``curl_cffi`` browser profile; ``"chrome"`` is a rolling alias that each ``curl_cffi``
+        release re-points at a newer Chrome, which is why ``curl_cffi`` carries a floor in headgate's manifest.
+    :param default_headers: let the profile supply the browser's headers (and drop httpx2's) instead of sending none.
+    :param curl_options: extra libcurl options, e.g. ``{CurlOpt.FRESH_CONNECT: True}`` to open a new connection per
+        request for hosts that fingerprint a reused one. Values are whatever libcurl takes for the option (``curl_cffi``
+        annotates them as ``str``, which is narrower than what it accepts).
+    :param max_connections: concurrent curl handles; a request beyond them waits for one, with no pool timeout.
+    """
+
+    def __init__(
+        self,
+        *,
+        impersonate: BrowserTypeLiteral,
+        default_headers: bool = False,
+        curl_options: Mapping[CurlOpt, Any] | None = None,
+        max_connections: int = 10,
+    ) -> None:
+        # curl reads the environment's proxy settings on its own, and an httpx2 transport ignores them
+        # (https://github.com/lexiforest/curl_cffi/issues/345).
+        options: dict[CurlOpt, Any] = {**(curl_options or {}), CurlOpt.NOPROXY: "*"}
+        self._default_headers = default_headers
+        self._session = _AsyncSession(
+            max_clients=max_connections,
+            impersonate=impersonate,
+            default_headers=default_headers,
+            curl_options=options,
+            trust_env=False,
+            discard_cookies=True,
+            allow_redirects=False,
+        )
+
+    @override
+    async def handle_async_request(self, request: httpx2.Request) -> httpx2.Response:
+        method = _METHODS.get(request.method)
+        if method is None:
+            msg = f"curl cannot send an HTTP {request.method} request"
+            raise httpx2.UnsupportedProtocol(msg, request=request)
+        await request.aread()
+        if self._default_headers:
+            for name, value in _httpx_default_headers():
+                if request.headers.get(name) == value:
+                    del request.headers[name]
+        try:
+            response = await self._session.request(
+                method=method,
+                url=str(request.url),
+                data=request.content,
+                headers=request.headers.raw,
+                timeout=_curl_timeout(request.extensions.get("timeout", {})),
+                stream=True,
+            )
+        except _RequestError as exc:
+            raise _httpx_error(request, exc) from exc
+        return _httpx_response(request, response)
+
+    @override
+    async def aclose(self) -> None:
+        await self._session.close()
+
+
+def _httpx_response(request: httpx2.Request, response: _Response) -> httpx2.Response:
+    """Wrap the streamed ``curl_cffi`` *response* as the httpx2 response a native transport returns.
+
+    ``elapsed`` is left to httpx2, which measures until the body is closed; curl's own figure stops at the headers.
+    """
+    headers = httpx2.Headers([(k, v or b"") for k, v in response.headers.raw])
+    if "content-encoding" in headers:
+        for name in _WIRE_ENCODING_HEADERS:
+            headers.pop(name, None)
+    extensions: dict[str, object] = {"curl": {"response": response, "infos": response.infos}}
+    if (http_version := _HTTP_VERSIONS.get(response.http_version)) is not None:
+        extensions["http_version"] = http_version
+    if response.reason:  # empty under HTTP/2 and HTTP/3
+        extensions["reason_phrase"] = response.reason.encode("ascii", "ignore")
+    return httpx2.Response(
+        status_code=response.status_code,
+        request=request,
+        headers=headers,
+        stream=_CurlByteStream(request, response),
+        extensions=extensions,
+    )
+
+
+class _CurlByteStream(httpx2.AsyncByteStream):
+    """The body of a streamed ``curl_cffi`` response, with curl's errors raised as httpx2 ones."""
+
+    def __init__(self, request: httpx2.Request, response: _Response) -> None:
+        self._request = request
+        self._response = response
+        # Set to make curl's write callback abort the transfer. Only a streamed response has one; for any other there
+        # is nothing left to abort, and a fresh event is never read.
+        self._abort: asyncio.Event = response.quit_now or asyncio.Event()
+
+    @override
+    async def __aiter__(self) -> AsyncIterator[bytes]:
+        try:
+            async for chunk in self._response.aiter_content():
+                yield bytes(chunk)  # `curl_cffi` leaves the chunk untyped; `bytes(bytes)` returns it without a copy
+        except _RequestError as exc:
+            raise _httpx_error(self._request, exc) from exc
+
+    @override
+    async def aclose(self) -> None:
+        # Without the abort, `aclose` waits for (and queues) the rest of the body.
+        self._abort.set()
+        await self._response.aclose()
+
+
+def _httpx_error(request: httpx2.Request, exc: _RequestError) -> httpx2.RequestError:
+    """Return the httpx2 exception a native transport raises for the curl failure *exc*."""
+    message = str(exc)
+    if exc.code == CurlECode.OPERATION_TIMEDOUT:
+        kind: type[httpx2.RequestError] = _timeout_error(message)
+    else:
+        kind = _CURL_ERRORS.get(exc.code, httpx2.TransportError)
+    return kind(message, request=request)
+
+
+def _timeout_error(message: str) -> type[httpx2.TimeoutException]:
+    """Return :class:`httpx2.ConnectTimeout` for a timeout before the connection was up, else ``ReadTimeout``."""
+    if any(marker in message for marker in _CONNECT_TIMEOUT_MESSAGES):
+        return httpx2.ConnectTimeout
+    return httpx2.ReadTimeout
+
+
+def _curl_timeout(timeout: Mapping[str, float | None]) -> tuple[float, float] | None:
+    """Return the ``(connect, read)`` pair curl takes for httpx2's *timeout* extension.
+
+    curl has a connect timeout and, in stream mode, a stall window of ``connect + read`` seconds; httpx2's ``write`` and
+    ``pool`` have no curl twin. A ``None`` (no limit) becomes curl's own "no limit" (``0``, or no tuple at all for an
+    unlimited read), which never makes a limit tighter than the one asked for. A missing key means no limit too: a
+    transport above may rebuild the request without the extension, as hishel does.
+    """
+    read = timeout.get("read")
+    if read is None:
+        return None
+    return (timeout.get("connect") or 0.0, read)
+
+
+@functools.cache
+def _httpx_default_headers() -> tuple[tuple[str, str], ...]:
+    """Return the headers httpx2 and headgate add to a request the caller gave none.
+
+    httpx2's are read from a client rather than hard-coded; headgate's is the ``User-Agent`` of a client without a
+    product token of its own.
+    """
+    with httpx2.Client(trust_env=False) as client:
+        return (*client.headers.items(), ("user-agent", DEFAULT_USER_AGENT))

headgate/_deprecation.py

@@ -0,0 +1,101 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""Endpoint deprecation and sunset announcements: the ``Deprecation`` (RFC 9745) and ``Sunset`` (RFC 8594) headers.
+
+A provider retiring an endpoint says so on every response from it. :func:`deprecation_of` reads what a response
+announces into a :class:`~headgate.events.Deprecated` event, and :func:`announce_deprecation` emits it to the call's
+observers, once per call, from the final response's head.
+
+Both formats of ``Deprecation`` are read: RFC 9745's structured-field date (``@1688169599``, seconds since the epoch)
+and the older drafts' ``true`` or HTTP-date. ``Sunset`` is an HTTP-date. A header whose value is neither is ignored, as
+RFC 9745 asks of an invalid one. The ``Link`` targets with ``rel="deprecation"`` and ``rel="sunset"`` are reported
+when either header is, resolved against the request URL and with any credential in them redacted.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from typing import TYPE_CHECKING, Final
+
+from headgate._core import Deprecated
+from headgate._url import sanitize_url
+
+if TYPE_CHECKING:
+    import httpx2
+
+    from headgate._core import CallContext, CallInfo
+
+__all__ = ["announce_deprecation", "deprecation_of", "parse_deprecation", "parse_http_date"]
+
+#: An RFC 8941 Date: ``@`` and an Integer of at most 15 digits.
+_SF_DATE: Final = re.compile(r"@(-?[0-9]{1,15})")
+
+#: What parsing a date can raise: a value ``parsedate_to_datetime`` rejects, or a timestamp past ``datetime``'s range.
+_DATE_ERRORS = (TypeError, ValueError, OverflowError, OSError)
+
+
+def parse_http_date(value: str) -> datetime | None:
+    """Return the HTTP-date *value* as an aware UTC ``datetime``, or ``None`` when it is not one."""
+    try:
+        when = parsedate_to_datetime(value.strip())
+    except _DATE_ERRORS:
+        return None
+    return when.replace(tzinfo=UTC) if when.tzinfo is None else when.astimezone(UTC)
+
+
+def parse_deprecation(value: str) -> tuple[bool, datetime | None]:
+    """Return whether a ``Deprecation`` header *value* is valid, and the date it names.
+
+    ``@<seconds>`` (RFC 9745) and an HTTP-date name a date; ``true`` (the older drafts) names none. Anything else is
+    invalid: ``(False, None)``.
+    """
+    text = value.strip()
+    if (match := _SF_DATE.fullmatch(text)) is not None:
+        try:
+            return True, datetime.fromtimestamp(int(match[1]), UTC)
+        except _DATE_ERRORS:
+            return False, None
+    if text.lower() == "true":
+        return True, None
+    when = parse_http_date(text)
+    return when is not None, when
+
+
+def _link(response: httpx2.Response, rel: str) -> str | None:
+    """Return the target of *response*'s ``Link`` with relation *rel*, resolved and sanitized, or ``None``."""
+    target = response.links.get(rel, {}).get("url")
+    if target is None:
+        return None
+    return sanitize_url(str(response.request.url.join(target)))
+
+
+def deprecation_of(response: httpx2.Response, call: CallInfo) -> Deprecated | None:
+    """Return the :class:`~headgate.events.Deprecated` event *response* announces for *call*, or ``None``.
+
+    ``None`` unless the response carries a valid ``Deprecation`` or ``Sunset`` header.
+    """
+    deprecation = response.headers.get("Deprecation")
+    sunset = response.headers.get("Sunset")
+    if deprecation is None and sunset is None:
+        return None
+    deprecated, deprecated_at = (False, None) if deprecation is None else parse_deprecation(deprecation)
+    sunset_at = None if sunset is None else parse_http_date(sunset)
+    if not deprecated and sunset_at is None:
+        return None
+    return Deprecated(
+        call=call,
+        deprecated=deprecated,
+        deprecated_at=deprecated_at,
+        sunset_at=sunset_at,
+        link=_link(response, "deprecation"),
+        sunset_link=_link(response, "sunset"),
+    )
+
+
+def announce_deprecation(context: CallContext, response: httpx2.Response) -> None:
+    """Emit the :class:`~headgate.events.Deprecated` event *response* announces, when the call has observers."""
+    if context.observed and (event := deprecation_of(response, context.info)) is not None:
+        context.emit(event)