headgate 0.2.0__py3-none-any.whl

headgate/_codec.py

@@ -0,0 +1,24 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""Codec-neutral request-body preparation shared by every flavor's ``to_builtins``."""
+
+from __future__ import annotations
+
+__all__ = ["drop_none"]
+
+
+def drop_none(obj: object) -> object:
+    """Return *obj* with every ``None``-valued key removed, walking nested dicts, lists and tuples.
+
+    Every other value survives, so ``False``, ``0`` and ``""`` stay (unlike msgspec's ``omit_defaults``; like
+    pydantic's ``exclude_none``). Insertion order is preserved. Tuples are walked because ``msgspec.to_builtins`` keeps
+    a ``tuple`` field as a tuple, and the structs inside one have ``None`` fields like any other.
+    """
+    if isinstance(obj, dict):
+        return {k: drop_none(v) for k, v in obj.items() if v is not None}
+    if isinstance(obj, list):
+        return [drop_none(v) for v in obj]
+    if isinstance(obj, tuple):
+        return tuple(drop_none(v) for v in obj)
+    return obj

headgate/_core/__init__.py

@@ -0,0 +1,88 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""The shared core every layer may import: time, origins, the per-call context, events and the policy switch.
+
+It imports only the standard library and ``httpx2``, so the policy subpackages (:mod:`headgate.retry`,
+:mod:`headgate.breaker`, :mod:`headgate.ratelimit`) can depend on it and on nothing else of headgate's. Coordination
+between those subpackages goes through what is defined here and is wired together in :mod:`headgate._stack`.
+"""
+
+from headgate._core._context import CallContext, SendProgress, Slot
+from headgate._core._events import (
+    OBSERVER_FAILURES,
+    SILENT,
+    AttemptFinished,
+    BreakerChanged,
+    BreakerState,
+    CacheOutcome,
+    CacheResult,
+    CallEvent,
+    CallFinished,
+    CallInfo,
+    CallStarted,
+    Deprecated,
+    Emitter,
+    Event,
+    Observer,
+    RateLimited,
+    RetryScheduled,
+)
+from headgate._core._origin import origin_of, origin_text, same_origin
+from headgate._core._retry_after import RETRY_AFTER_STATUSES, parse_retry_after, retry_after_of
+from headgate._core._seams import BREAKER_GATE, CredentialCarrier, CredentialStamper
+from headgate._core._switch import policy_disabled, policy_is_disabled
+from headgate._core._time import (
+    SYSTEM_TIMING,
+    Clock,
+    RandomSource,
+    Sleep,
+    Timing,
+    asyncio_sleep,
+    current_timing,
+    system_random,
+    timing_override,
+)
+
+__all__ = [
+    "BREAKER_GATE",
+    "OBSERVER_FAILURES",
+    "RETRY_AFTER_STATUSES",
+    "SILENT",
+    "SYSTEM_TIMING",
+    "AttemptFinished",
+    "BreakerChanged",
+    "BreakerState",
+    "CacheOutcome",
+    "CacheResult",
+    "CallContext",
+    "CallEvent",
+    "CallFinished",
+    "CallInfo",
+    "CallStarted",
+    "Clock",
+    "CredentialCarrier",
+    "CredentialStamper",
+    "Deprecated",
+    "Emitter",
+    "Event",
+    "Observer",
+    "RandomSource",
+    "RateLimited",
+    "RetryScheduled",
+    "SendProgress",
+    "Sleep",
+    "Slot",
+    "Timing",
+    "asyncio_sleep",
+    "current_timing",
+    "origin_of",
+    "origin_text",
+    "parse_retry_after",
+    "policy_disabled",
+    "policy_is_disabled",
+    "retry_after_of",
+    "same_origin",
+    "system_random",
+    "timing_override",
+]

headgate/_core/_context.py

@@ -0,0 +1,228 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""The per-call context: what every layer of the stack knows about the logical call a request belongs to.
+
+``AsyncBaseClient`` builds one :class:`CallContext` per call and stamps it on the request in a single extension.
+httpx2 hands a request's extensions to every redirect hop, and the cache layer restores them below hishel, so every
+layer from the auth flow down to the network transport finds the same object with :meth:`CallContext.find`. Layers
+read and write it through its methods, never through extension keys of their own:
+
+* what the call is: :attr:`~CallContext.info` (method, sanitized URL, route template, call id);
+* when it must end: :attr:`~CallContext.deadline`, absolute on the client's clock, :meth:`~CallContext.remaining`,
+  and :meth:`~CallContext.fit_timeouts`, which cuts a request's timeouts to it;
+* its sends: :meth:`~CallContext.begin_attempt`, :attr:`~CallContext.attempt` and the current attempt's
+  :attr:`~CallContext.progress` (whether a connection was obtained and how many request bytes were written);
+* what it carries: :attr:`~CallContext.idempotency_key` and whether its redirects are followed;
+* what happened: :meth:`~CallContext.add_note` lines, which the client adds to the error it raises, and
+  :meth:`~CallContext.emit` for events;
+* per-layer data: a layer that needs a value of its own on the call declares a typed :class:`Slot` in its own module and
+  reads and writes it with :meth:`~CallContext.get` and :meth:`~CallContext.put`.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Final, cast, override
+
+from headgate._core._events import SILENT, CallInfo
+
+if TYPE_CHECKING:
+    import httpx2
+
+    from headgate._core._events import Emitter, Event
+    from headgate._core._time import Clock
+
+__all__ = ["CallContext", "SendProgress", "Slot"]
+
+#: The one request extension headgate keeps its per-call state in.
+_EXTENSION: Final = "headgate.call"
+
+
+@dataclass(slots=True)
+class SendProgress:
+    """What one attempt established about sending: whether a connection was obtained, and request bytes written.
+
+    These are facts, recorded by whichever layer can observe them, so the retry layer can tell a request that never
+    left from one that may have been processed.
+    """
+
+    connected: bool = False
+    bytes_sent: int = 0
+
+    def mark_connected(self) -> None:
+        """Record that the attempt obtained a connection."""
+        self.connected = True
+
+    def add_sent(self, count: int) -> None:
+        """Record that *count* more request bytes were written."""
+        self.bytes_sent += count
+
+
+class Slot[T]:
+    """A typed key for a value one layer keeps on a :class:`CallContext`; compared by identity."""
+
+    __slots__ = ("name",)
+
+    def __init__(self, name: str) -> None:
+        """Name the slot, for its ``repr`` only."""
+        self.name = name
+
+    @override
+    def __repr__(self) -> str:
+        """Return ``Slot('name')``."""
+        return f"Slot({self.name!r})"
+
+
+class CallContext:
+    """One logical call's state, shared by every layer that handles one of its requests. See the module docstring."""
+
+    __slots__ = (
+        "_attempt",
+        "_clock",
+        "_deadline",
+        "_emitter",
+        "_notes",
+        "_progress",
+        "_slots",
+        "follow_redirects",
+        "idempotency_key",
+        "info",
+        "started_at",
+    )
+
+    def __init__(
+        self,
+        info: CallInfo,
+        *,
+        clock: Clock = time.monotonic,
+        deadline_after: float | None = None,
+        emitter: Emitter = SILENT,
+    ) -> None:
+        """Start the call *info* now on *clock*, due *deadline_after* seconds from now (``None``: no deadline)."""
+        self.info = info
+        self._clock = clock
+        self.started_at = clock()
+        self._deadline = None if deadline_after is None else self.started_at + deadline_after
+        self._emitter = emitter
+        self._attempt = 0
+        self._progress = SendProgress()
+        self._notes: list[str] = []
+        self._slots: dict[object, object] = {}
+        #: The ``Idempotency-Key`` (or configured header) value every attempt of the call carries, if any.
+        self.idempotency_key: str | None = None
+        #: Whether httpx2 follows this call's redirects, read by the hook that drops a followed redirect's body.
+        self.follow_redirects = True
+
+    # Finding the context of a request.
+
+    def attach(self, request: httpx2.Request) -> None:
+        """Stamp this context on *request*."""
+        request.extensions[_EXTENSION] = self
+
+    @staticmethod
+    def find(request: httpx2.Request) -> CallContext | None:
+        """Return the context stamped on *request*, or ``None`` for a request no client call built."""
+        found = request.extensions.get(_EXTENSION)
+        return found if isinstance(found, CallContext) else None
+
+    @staticmethod
+    def of(request: httpx2.Request) -> CallContext:
+        """Return the context stamped on *request*, stamping a standalone one first when it has none.
+
+        A request a layer is handed directly (a test driving one transport, a hop an auth flow built) has no client
+        call around it; its standalone context names the request's origin and path only, and has no deadline.
+        """
+        found = CallContext.find(request)
+        if found is not None:
+            return found
+        bare = request.url.copy_with(query=None, fragment=None, userinfo=b"")
+        context = CallContext(CallInfo(method=request.method, url=str(bare)))
+        context.attach(request)
+        return context
+
+    # Time.
+
+    @property
+    def clock(self) -> Clock:
+        """The clock the deadline and every duration of this call are measured on."""
+        return self._clock
+
+    @property
+    def deadline(self) -> float | None:
+        """The clock reading by which the call must end, or ``None`` when it has no deadline."""
+        return self._deadline
+
+    def remaining(self) -> float | None:
+        """Return the seconds left before the deadline (negative once past it), or ``None`` without a deadline."""
+        return None if self._deadline is None else self._deadline - self._clock()
+
+    def elapsed(self) -> float:
+        """Return the seconds since the call started."""
+        return self._clock() - self.started_at
+
+    def fit_timeouts(self, request: httpx2.Request, *, floor: float = 0.0) -> None:
+        """Cut *request*'s httpx2 timeouts to the time left before the deadline, never below *floor* seconds.
+
+        Each phase keeps its own limit when that is shorter; a phase with no limit gets the time left. A call without a
+        deadline, or a request without a ``timeout`` extension, is left as it is. Every layer that waits before a send
+        calls it, so the send that follows cannot outlast the call.
+        """
+        remaining = self.remaining()
+        timeout = request.extensions.get("timeout")
+        if remaining is None or not isinstance(timeout, dict):
+            return
+        left = max(remaining, floor)
+        request.extensions["timeout"] = {
+            phase: left if limit is None else min(limit, left) for phase, limit in timeout.items()
+        }
+
+    # Attempts.
+
+    @property
+    def attempt(self) -> int:
+        """How many sends the call has begun: 0 before the first, then 1, 2, ..."""
+        return self._attempt
+
+    @property
+    def progress(self) -> SendProgress:
+        """The current attempt's send progress, fresh for each attempt."""
+        return self._progress
+
+    def begin_attempt(self) -> int:
+        """Record that a send begins, reset the send progress, and return the attempt's number (from 1)."""
+        self._attempt += 1
+        self._progress = SendProgress()
+        return self._attempt
+
+    # Notes and events.
+
+    @property
+    def notes(self) -> tuple[str, ...]:
+        """The lines layers added about the call, in order."""
+        return tuple(self._notes)
+
+    def add_note(self, note: str) -> None:
+        """Add *note*, a line with no credential in it, for the error the call may raise."""
+        self._notes.append(note)
+
+    @property
+    def observed(self) -> bool:
+        """Whether the client has observers, so a layer can skip building an event nobody receives."""
+        return self._emitter.active
+
+    def emit(self, event: Event) -> None:
+        """Deliver *event* to the client's observers."""
+        self._emitter.emit(event)
+
+    # Per-layer data.
+
+    def get[T](self, slot: Slot[T]) -> T | None:
+        """Return the value put in *slot*, or ``None``."""
+        # A slot is only ever filled through put(), with a value of its own type.
+        return cast("T | None", self._slots.get(slot))
+
+    def put[T](self, slot: Slot[T], value: T) -> None:
+        """Put *value* in *slot*."""
+        self._slots[slot] = value

headgate/_core/_events.py

@@ -0,0 +1,248 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""Typed events: what a client reports about its calls, instead of logging.
+
+Every event is a frozen value carrying sanitized data only: a URL with its credentials redacted, a method, the route
+template, statuses, exception type names and durations on the client's clock. No header, body or credential is ever
+put in one. :mod:`headgate.events` is the public face of this module.
+
+An :class:`Observer` installed through ``HttpOptions(observers=...)`` receives them. Observers run inline, in the order
+they were given, so one should hand slow work to a queue. An exception an observer raises never reaches the call: the
+:class:`Emitter` swallows it and counts it in :data:`OBSERVER_FAILURES`, which ``headgate.health.observer_failures``
+reads.
+
+The event set is defined here, below the policy subpackages, so that every layer can emit the events it owns through
+the call's :class:`~headgate._core.CallContext`.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import itertools
+from collections import Counter
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import TYPE_CHECKING, Protocol
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+__all__ = [
+    "OBSERVER_FAILURES",
+    "SILENT",
+    "AttemptFinished",
+    "BreakerChanged",
+    "BreakerState",
+    "CacheOutcome",
+    "CacheResult",
+    "CallEvent",
+    "CallFinished",
+    "CallInfo",
+    "CallStarted",
+    "Deprecated",
+    "Emitter",
+    "Event",
+    "Observer",
+    "RateLimited",
+    "RetryScheduled",
+]
+
+#: Process-unique call ids, so an observer can group the events of one call among many concurrent ones.
+_CALL_IDS = itertools.count(1)
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CallInfo:
+    """What identifies one logical call in every event about it.
+
+    ``url`` is the URL the call was given, sanitized and bounded; ``route`` is the t-string template the URL was
+    rendered from (``"series/{series_id}"``), or ``None`` for a ``str`` URL. ``full_url`` is the absolute URL of the
+    request as first built (before any redirect), sanitized: what an observer needs to name the server, as an
+    OpenTelemetry span does. It is ``None`` when the client has no observers.
+    """
+
+    method: str
+    url: str
+    route: str | None = None
+    full_url: str | None = None
+    call_id: int = field(default_factory=lambda: next(_CALL_IDS))
+
+
+class BreakerState(StrEnum):
+    """Circuit-breaker states; the value is what a breaker reports."""
+
+    CLOSED = "closed"
+    OPEN = "open"
+    HALF_OPEN = "half_open"
+
+
+class CacheOutcome(StrEnum):
+    """What the HTTP cache did for one request.
+
+    * ``HIT``: a stored response answered it;
+    * ``MISS``: it went to the network (and its response may have been stored);
+    * ``SHARED``: it waited on an identical request's download and got a copy of its response, or its failure;
+    * ``DEGRADED``: the storage failed, so it went to the network uncached.
+
+    The cache is TTL-only and never revalidates an entry with the origin, so there is no revalidated outcome.
+    """
+
+    HIT = "hit"
+    MISS = "miss"
+    SHARED = "shared"
+    DEGRADED = "degraded"
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CallEvent:
+    """Base of every event about one call: :attr:`call` names it."""
+
+    call: CallInfo
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CallStarted(CallEvent):
+    """A call's request was built and is about to be sent."""
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class AttemptFinished(CallEvent):
+    """One send of the call finished: a response head arrived (``status_code``) or it raised (``error``, a type name).
+
+    ``attempt`` counts from 1 across the call's sends, retries and followed redirects included; ``elapsed`` is the
+    send's duration in seconds on the client's clock.
+    """
+
+    attempt: int
+    status_code: int | None = None
+    error: str | None = None
+    elapsed: float
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RetryScheduled(CallEvent):
+    """The retry layer will send the call again after ``delay`` seconds, because of ``reason``."""
+
+    attempt: int
+    delay: float
+    reason: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class RateLimited(CallEvent):
+    """The call's rate budget held it back, or its response paused the budget, for ``delay`` seconds.
+
+    ``reason`` says which: ``"paced"`` or ``"throttled"``, the call waited for its turn at the configured rate or at
+    the rate adaptive throttling lowered it to; ``"paused"``, it waited out a pause the server asked for; and
+    ``"pushback"``, its own response asked for that pause, which every call sharing the budget then waits out.
+    """
+
+    delay: float
+    reason: str
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CacheResult(CallEvent):
+    """What the HTTP cache did for the call."""
+
+    outcome: CacheOutcome
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class Deprecated(CallEvent):
+    """The call's response announced that its endpoint is deprecated (RFC 9745) or will be sunset (RFC 8594).
+
+    * ``deprecated``: the response carried a valid ``Deprecation`` header;
+    * ``deprecated_at``: the date it names (in the past: deprecated since then; in the future: deprecated from then),
+      or ``None`` for the older ``Deprecation: true`` and for a response with only a ``Sunset`` header;
+    * ``sunset_at``: the ``Sunset`` date, after which the endpoint may stop answering, or ``None``;
+    * ``link`` / ``sunset_link``: the ``Link`` targets with ``rel="deprecation"`` / ``rel="sunset"`` (where the
+      provider documents the change), resolved against the request URL and with credentials redacted.
+    """
+
+    deprecated: bool = False
+    deprecated_at: datetime | None = None
+    sunset_at: datetime | None = None
+    link: str | None = None
+    sunset_link: str | None = None
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class CallFinished(CallEvent):
+    """A call ended: with the final ``status_code``, or raising ``error`` (the ``ClientError`` type name).
+
+    ``attempts`` is how many sends it made; ``elapsed`` its whole duration in seconds on the client's clock.
+    """
+
+    status_code: int | None = None
+    error: str | None = None
+    attempts: int
+    elapsed: float
+
+
+@dataclass(frozen=True, slots=True, kw_only=True)
+class BreakerChanged:
+    """An origin's circuit breaker moved from ``previous`` to ``state``; ``call`` is the call that moved it, if any."""
+
+    origin: str
+    previous: BreakerState
+    state: BreakerState
+    failures: int
+    call: CallInfo | None = None
+
+
+type Event = (
+    CallStarted
+    | AttemptFinished
+    | RetryScheduled
+    | RateLimited
+    | BreakerChanged
+    | CacheResult
+    | Deprecated
+    | CallFinished
+)
+"""Every event a client emits."""
+
+
+class Observer(Protocol):
+    """Receives a client's events. Installed with ``HttpOptions(observers=(...))``."""
+
+    def notify(self, event: Event) -> None:
+        """Handle *event*; any exception raised here is counted and swallowed, never raised into the call."""
+        ...
+
+
+#: How many times each observer class raised from ``notify``, since process start.
+OBSERVER_FAILURES: Counter[str] = Counter()
+
+
+class Emitter:
+    """Deliver events to a client's observers, isolating the call from any observer's failure."""
+
+    __slots__ = ("_observers",)
+
+    def __init__(self, observers: tuple[Observer, ...] = ()) -> None:
+        """Deliver to *observers*, in order."""
+        self._observers = observers
+
+    @property
+    def active(self) -> bool:
+        """Whether anyone is listening, so a hot path can skip building an event nobody receives."""
+        return bool(self._observers)
+
+    def emit(self, event: Event) -> None:
+        """Hand *event* to every observer; one that raises is counted in :data:`OBSERVER_FAILURES` and skipped."""
+        for observer in self._observers:
+            delivered = False
+            # An observer is the caller's code, outside headgate's error contract: whatever it raises must not
+            # change the call's outcome, and headgate never logs, so the count is the whole record.
+            with contextlib.suppress(Exception):
+                observer.notify(event)
+                delivered = True
+            if not delivered:
+                OBSERVER_FAILURES[type(observer).__qualname__] += 1
+
+
+#: The emitter of a client with no observers.
+SILENT = Emitter()

headgate/_core/_origin.py

@@ -0,0 +1,39 @@
+# Copyright (c) 2026 Khaled Elsayed
+# SPDX-License-Identifier: MIT
+
+"""Origins (RFC 6454 / RFC 9110 section 4.3.1): the scheme, host and effective port a URL addresses.
+
+``httpx2.Origin`` does the normalisation (lower-case scheme and host, the default port filled in, IPv6 in canonical
+form); these helpers name the operations every layer that keys or compares by origin needs.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+import httpx2
+
+__all__ = ["origin_of", "origin_text", "same_origin"]
+
+#: The port each scheme implies, left out of :func:`origin_text`.
+_DEFAULT_PORTS: Final = {"http": 80, "https": 443, "ws": 80, "wss": 443}
+
+
+def origin_of(url: httpx2.URL | str) -> httpx2.Origin:
+    """Return *url*'s origin.
+
+    :raises ValueError: for a relative URL, which has none.
+    """
+    return httpx2.Origin(url)
+
+
+def origin_text(origin: httpx2.Origin) -> str:
+    """Return *origin* as ``scheme://host[:port]``, leaving out the scheme's default port and bracketing IPv6."""
+    host = f"[{origin.host}]" if ":" in origin.host else origin.host
+    port = "" if origin.port in {None, _DEFAULT_PORTS.get(origin.scheme)} else f":{origin.port}"
+    return f"{origin.scheme}://{host}{port}"
+
+
+def same_origin(a: httpx2.URL | str, b: httpx2.URL | str) -> bool:
+    """Return whether two absolute URLs address the same origin."""
+    return origin_of(a) == origin_of(b)