clientwright 0.1.0__py3-none-any.whl

clientwright/adapters/_lazy.py

@@ -0,0 +1,30 @@
+"""Lazy re-exports for adapter packages.
+
+Importing an adapter package must NOT import its SDK. The registry reaches
+``<adapter>.capabilities`` *through* the package, and Python executes a
+package's ``__init__`` before any submodule of it - so an eager
+``from .adapter import ...`` there would drag the SDK in and break
+``capabilities_matrix()`` on a bare install, which is exactly the promise the
+zero-dependency core exists to keep.
+
+Each adapter therefore maps its public names to submodules and resolves them on
+first attribute access; the SDK's install hint surfaces then, not at import.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+
+def lazy_attribute(package: str, namespace: dict[str, Any], exports: dict[str, str], name: str) -> Any:
+    """Resolve ``name`` from its submodule and cache it in the package namespace."""
+    submodule = exports.get(name)
+    if submodule is None:
+        raise AttributeError(f"module {package!r} has no attribute {name!r}")
+    value = getattr(importlib.import_module(f".{submodule}", package), name)
+    namespace[name] = value
+    return value
+
+
+__all__ = ["lazy_attribute"]

clientwright/adapters/aiohttp/__init__.py

@@ -0,0 +1,45 @@
+"""aiohttp adapter (``[aiohttp]`` extra): real ClientSession, engine underneath.
+
+Names resolve lazily (see ``clientwright.adapters._lazy``): importing this
+package never imports aiohttp, so the capabilities matrix stays extras-free.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .._lazy import lazy_attribute
+
+if TYPE_CHECKING:
+    from .adapter import AiohttpAdapter as AiohttpAdapter
+    from .capabilities import CAPABILITIES as CAPABILITIES
+    from .errors import AiohttpCircuitOpenError as AiohttpCircuitOpenError
+    from .errors import AiohttpDeadlineExceededError as AiohttpDeadlineExceededError
+    from .errors import AiohttpTooManyRedirectsError as AiohttpTooManyRedirectsError
+    from .options import CallOptions as CallOptions
+    from .options import call_options as call_options
+
+_EXPORTS = {
+    "CAPABILITIES": "capabilities",
+    "AiohttpAdapter": "adapter",
+    "AiohttpCircuitOpenError": "errors",
+    "AiohttpDeadlineExceededError": "errors",
+    "AiohttpTooManyRedirectsError": "errors",
+    "CallOptions": "options",
+    "call_options": "options",
+}
+
+
+def __getattr__(name: str) -> Any:
+    return lazy_attribute(__name__, globals(), _EXPORTS, name)
+
+
+__all__ = [
+    "CAPABILITIES",
+    "AiohttpAdapter",
+    "AiohttpCircuitOpenError",
+    "AiohttpDeadlineExceededError",
+    "AiohttpTooManyRedirectsError",
+    "CallOptions",
+    "call_options",
+]

clientwright/adapters/aiohttp/_imports.py

@@ -0,0 +1,30 @@
+"""Lazy import guard for the optional aiohttp stack.
+
+Importing this module fails with a friendly message when the ``aiohttp`` extra
+is not installed, so ``import clientwright`` never pays the cost (or the
+failure). Every aiohttp submodule imports its third-party symbols from here.
+
+The adapter needs aiohttp>=3.12: earlier releases have no client middleware,
+which is the only seam that can mutate requests and own the retry loop.
+"""
+
+from __future__ import annotations
+
+import inspect
+
+_INSTALL_HINT = "aiohttp support requires clientwright[aiohttp]; install it."
+_VERSION_HINT = (
+    "clientwright's aiohttp adapter requires aiohttp>=3.12 (client middleware); "
+    "the installed version has no 'middlewares' parameter on ClientSession."
+)
+
+try:
+    import aiohttp
+    from yarl import URL
+except ImportError as exc:  # pragma: no cover - exercised only without the extra
+    raise ImportError(_INSTALL_HINT) from exc
+
+if "middlewares" not in inspect.signature(aiohttp.ClientSession.__init__).parameters:  # pragma: no cover
+    raise ImportError(_VERSION_HINT)
+
+__all__ = ["URL", "aiohttp"]

clientwright/adapters/aiohttp/adapter.py

@@ -0,0 +1,236 @@
+"""The aiohttp adapter: builds real ClientSession objects with the engine underneath.
+
+aiohttp constraints this builder honors (verified against aiohttp 3.12):
+- the session-level total timeout would wrap ALL our retries and backoff sleeps
+  (middleware runs inside the ``_request`` timer), so ``ClientTimeout.total``
+  is always None and the engine's monotonic deadline is the only total;
+- ``ceil_threshold`` is raised so aiohttp never rounds deadlines up to whole
+  seconds (the default ceils everything above 5s);
+- the native one-shot idempotent retry is invisible to middleware and is
+  silenced via the private ``_retry_connection`` attribute (declared DEGRADED);
+- ``ClientSession`` must be constructed inside a running event loop.
+"""
+
+from __future__ import annotations
+
+import ssl
+from collections.abc import Mapping
+from typing import Any
+from urllib.request import getproxies
+
+from ...core.capabilities import Capability
+from ...core.config import ClientConfig, is_set, resolve
+from ...core.contracts.adapter import AdapterDeps
+from ...core.engine.aio import AsyncAttemptEngine
+from ...core.errors import UnsupportedCapabilityError
+from ...core.model import ResolvedTimeouts
+from ...core.native import validate_native
+from ...core.plan import CallPlan, ClientHandle, ClientRuntime, compile_plan, register_handle
+from ...core.policy.timeout import base_timeouts
+from ...core.telemetry.emitter import ClientTelemetry
+from ._imports import aiohttp
+from .capabilities import CAPABILITIES
+from .errors import translate_call_error
+from .middleware import EngineMiddleware, ProxyRouter
+from .normalize import AsyncAiohttpNormalizer
+from .trace import build_trace_config
+
+# aiohttp's DEFAULT_TIMEOUT is ClientTimeout(total=5*60, sock_connect=30); the
+# closest per-phase reading: 30s to connect, no read/write/pool phases.
+_NATIVE_TIMEOUT_DEFAULTS = ResolvedTimeouts(connect=30.0, read=None, write=None, pool_acquire=None)
+
+# Above this threshold aiohttp ceils absolute deadlines to whole seconds; a
+# value no timeout reaches disables the rounding entirely.
+_NO_CEIL_THRESHOLD = 1e9
+
+_RESERVED_SESSION_KEYS: Mapping[str, str] = {
+    "connector": "the connector is built by clientwright; tune it via config or the 'connector' slot",
+    "connector_owner": "clientwright owns the connector lifecycle",
+    "middlewares": "middlewares belong to clientwright; the engine seam lives there",
+    "trace_configs": "trace_configs belong to clientwright (bypass sentinel and conn metrics)",
+    "timeout": "use ClientConfig.timeout",
+    "base_url": "use ClientConfig.base_url",
+    "headers": "use ClientConfig.headers",
+    "proxy": "use ClientConfig.proxy",
+}
+
+_RESERVED_CONNECTOR_KEYS: Mapping[str, str] = {
+    "limit": "use ClientConfig.pool.max_connections",
+    "limit_per_host": "use ClientConfig.pool.max_connections_per_host",
+    "keepalive_timeout": "use ClientConfig.pool.keepalive_expiry",
+    "force_close": "use ClientConfig.pool.keepalive_expiry=None",
+    "ssl": "use ClientConfig.tls",
+}
+
+
+def _ssl_argument(config: ClientConfig) -> ssl.SSLContext | bool:
+    tls = config.tls
+    if tls.ca_bundle is None and tls.cert is None:
+        return bool(tls.verify)
+    context = ssl.create_default_context(cafile=tls.ca_bundle)
+    if not tls.verify:
+        context.check_hostname = False
+        context.verify_mode = ssl.CERT_NONE
+    if tls.cert is not None:
+        if isinstance(tls.cert, str):
+            context.load_cert_chain(tls.cert)
+        else:
+            context.load_cert_chain(*tls.cert)
+    return context
+
+
+def _no_proxy_hosts(proxies: dict[str, str]) -> tuple[str, ...]:
+    raw = proxies.get("no", "")
+    return tuple(entry.strip() for entry in raw.split(",") if entry.strip() and entry.strip() != "*")
+
+
+def _proxy_router(config: ClientConfig) -> ProxyRouter | None:
+    if config.proxy is None:
+        return None
+    if config.proxy.url is not None:
+        return ProxyRouter(config.proxy.url)
+    proxies = getproxies()
+    by_scheme: dict[str, str] = {scheme: proxies[scheme] for scheme in ("http", "https") if scheme in proxies}
+    if not by_scheme:
+        return None
+    return ProxyRouter(None, by_scheme, _no_proxy_hosts(proxies))
+
+
+class AiohttpAdapter:
+    name = "aiohttp"
+    capabilities = CAPABILITIES
+    native_slots = frozenset({"session", "connector"})
+    reserved_keys: Mapping[str, Mapping[str, str]] = {
+        "session": _RESERVED_SESSION_KEYS,
+        "connector": _RESERVED_CONNECTOR_KEYS,
+    }
+    allowed_keys: Mapping[str, frozenset[str] | None] = {"session": None, "connector": None}
+
+    def _validated_native(self, config: ClientConfig) -> dict[str, dict[str, Any]]:
+        return validate_native(
+            config.native,
+            slots=self.native_slots,
+            reserved=self.reserved_keys,
+            allowed=self.allowed_keys,
+            signature_targets={"session": aiohttp.ClientSession, "connector": aiohttp.TCPConnector},
+            config_conflicts={},
+        )
+
+    def _compile(self, config: ClientConfig) -> CallPlan:
+        applied = {
+            Capability.TIMEOUT_CONNECT,
+            Capability.TIMEOUT_READ,
+            Capability.POOL_LIMIT_TOTAL,
+            Capability.KEEPALIVE,
+        }
+        if resolve(config.pool.max_connections_per_host, None) is not None:
+            applied.add(Capability.POOL_LIMIT_PER_HOST)
+        emulated = {Capability.TIMEOUT_TOTAL, Capability.TIMEOUT_ATTEMPT, Capability.DEADLINE_HARD}
+        if config.proxy is not None:
+            emulated.add(Capability.PROXY)
+        dropped: dict[Capability, str] = {}
+        if is_set(config.timeout.write) and resolve(config.timeout.write, None) is not None:
+            dropped[Capability.TIMEOUT_WRITE] = (
+                "aiohttp has no write timeout; a slow upload is bounded only by the attempt ceiling"
+            )
+        if is_set(config.timeout.pool_acquire) and resolve(config.timeout.pool_acquire, None) is not None:
+            dropped[Capability.TIMEOUT_POOL] = (
+                "aiohttp folds pool waiting into the connect phase; there is no separate pool timeout"
+            )
+        if resolve(config.pool.http2, False):
+            dropped[Capability.HTTP2] = "aiohttp speaks HTTP/1.1 only"
+        plan = compile_plan(
+            config,
+            CAPABILITIES,
+            native_timeout_defaults=_NATIVE_TIMEOUT_DEFAULTS,
+            applied_natively=frozenset(applied),
+            emulated=frozenset(emulated),
+            dropped=dropped,
+        )
+        plan.report.enforce(config.on_unsupported)
+        return plan
+
+    def _connector(self, config: ClientConfig, native_connector: dict[str, Any]) -> aiohttp.TCPConnector:
+        limit = resolve(config.pool.max_connections, 100)
+        per_host = resolve(config.pool.max_connections_per_host, None)
+        keepalive = resolve(config.pool.keepalive_expiry, 15.0)
+        kwargs: dict[str, Any] = {
+            "limit": 0 if limit is None else limit,
+            "limit_per_host": 0 if per_host is None else per_host,
+            "ssl": _ssl_argument(config),
+        }
+        if keepalive is None:
+            kwargs["force_close"] = True
+        else:
+            kwargs["keepalive_timeout"] = keepalive
+        kwargs.update(native_connector)
+        return aiohttp.TCPConnector(**kwargs)
+
+    def build_async(self, config: ClientConfig, deps: AdapterDeps) -> ClientHandle[Any]:
+        native = self._validated_native(config)
+        telemetry = ClientTelemetry(
+            service=config.service_name,
+            adapter=self.name,
+            seam=CAPABILITIES.seam,
+            config=config.observability,
+            metrics=deps.metrics,
+            tracer=deps.tracer,
+        )
+        runtime = deps.runtime or ClientRuntime.for_config(
+            config, clock=deps.clock, circuit_listener=telemetry.circuit_state_changed
+        )
+        plan = self._compile(config)
+        base = base_timeouts(config.timeout, _NATIVE_TIMEOUT_DEFAULTS)
+        engine = AsyncAttemptEngine(
+            plan=plan,
+            runtime=runtime,
+            telemetry=telemetry,
+            normalizer=AsyncAiohttpNormalizer(),
+            deps=deps,
+            translate=translate_call_error,
+        )
+        middleware = EngineMiddleware(engine, _proxy_router(config))
+        # total=None ON PURPOSE: aiohttp's total timer would wrap the engine's
+        # whole retry loop, sleeps included. The engine's deadline is the total.
+        client_timeout = aiohttp.ClientTimeout(
+            total=None,
+            connect=base.connect,
+            sock_read=base.read,
+            ceil_threshold=_NO_CEIL_THRESHOLD,
+        )
+        session_kwargs: dict[str, Any] = dict(native.get("session", {}))
+        if config.base_url is not None:
+            session_kwargs["base_url"] = config.base_url
+        session = aiohttp.ClientSession(
+            connector=self._connector(config, native.get("connector", {})),
+            timeout=client_timeout,
+            middlewares=(middleware,),
+            trace_configs=[build_trace_config(telemetry, runtime.clock)],
+            **session_kwargs,
+        )
+        try:
+            # The hidden one-shot idempotent retry would multiply our attempt
+            # count outside the metrics; the name is listed in ClientSession.ATTRS.
+            session._retry_connection = False
+        except AttributeError:  # pragma: no cover - future aiohttp may drop the attribute
+            pass
+        handle: ClientHandle[Any] = ClientHandle(
+            client=session,
+            adapter=self.name,
+            capabilities=CAPABILITIES,
+            report=plan.report,
+            runtime=runtime,
+            plan=plan,
+            aclose=session.close,
+        )
+        register_handle(session, handle)
+        return handle
+
+    def build_sync(self, config: ClientConfig, deps: AdapterDeps) -> ClientHandle[Any]:
+        raise UnsupportedCapabilityError(
+            "aiohttp is async-only: there is no sync client to build; use build() or build_handle(), "
+            "or pick an adapter with a sync flavor (httpx, requests, urllib3)"
+        )
+
+
+__all__ = ["AiohttpAdapter"]

clientwright/adapters/aiohttp/capabilities.py

@@ -0,0 +1,81 @@
+"""aiohttp capability declaration. Zero-dependency: never imports aiohttp."""
+
+from __future__ import annotations
+
+from ...core.capabilities import (
+    AdapterCapabilities,
+    Capability,
+    DurationBoundary,
+    SeamGranularity,
+    Support,
+)
+from ...core.model import FailureKind
+
+CAPABILITIES = AdapterCapabilities(
+    adapter="aiohttp",
+    seam="middleware",
+    granularity=SeamGranularity.HOP,
+    boundary=DurationBoundary.HEADERS,
+    support={
+        Capability.TIMEOUT_TOTAL: Support.EMULATED,
+        Capability.TIMEOUT_ATTEMPT: Support.EMULATED,
+        Capability.TIMEOUT_CONNECT: Support.NATIVE,
+        Capability.TIMEOUT_READ: Support.NATIVE,
+        Capability.TIMEOUT_WRITE: Support.ABSENT,
+        Capability.TIMEOUT_POOL: Support.ABSENT,
+        Capability.DEADLINE_HARD: Support.EMULATED,
+        Capability.POOL_LIMIT_TOTAL: Support.NATIVE,
+        Capability.POOL_LIMIT_PER_HOST: Support.NATIVE,
+        Capability.KEEPALIVE: Support.NATIVE,
+        Capability.POOL_METRICS: Support.NATIVE,
+        Capability.CONN_METRICS: Support.NATIVE,
+        Capability.REDIRECTS_OWNABLE: Support.NATIVE,
+        Capability.NATIVE_RETRY_DISABLEABLE: Support.DEGRADED,
+        Capability.PER_CALL_OPTIONS: Support.EMULATED,
+        Capability.RETROFIT: Support.ABSENT,
+        Capability.EXACT_NATIVE_TYPE: Support.NATIVE,
+        Capability.BALANCER: Support.ABSENT,
+        Capability.HTTP2: Support.ABSENT,
+        Capability.HTTP3: Support.ABSENT,
+        Capability.PROXY: Support.EMULATED,
+    },
+    emits=frozenset(
+        {
+            FailureKind.CONNECT_TIMEOUT,
+            FailureKind.READ_TIMEOUT,
+            FailureKind.TOTAL_TIMEOUT,
+            FailureKind.CONNECT_ERROR,
+            FailureKind.DNS_ERROR,
+            FailureKind.TLS_ERROR,
+            FailureKind.PROTOCOL_ERROR,
+            FailureKind.DISCONNECTED,
+            FailureKind.STATUS,
+            FailureKind.CANCELLED,
+            FailureKind.CIRCUIT_OPEN,
+            FailureKind.UNKNOWN,
+        }
+    ),
+    collapses={
+        FailureKind.POOL_TIMEOUT: FailureKind.CONNECT_TIMEOUT,
+        FailureKind.WRITE_TIMEOUT: FailureKind.TOTAL_TIMEOUT,
+    },
+    notes={
+        "async_only": "aiohttp has no sync client; build_sync raises. The session must be built inside a running loop.",
+        "timeout_write": "aiohttp has no write timeout; a slow upload is bounded only by the attempt ceiling.",
+        "timeout_pool": "Pool waiting is folded into the connect phase; on_connection_queued metrics expose it.",
+        "per_call_options": "No request extensions; route/idempotency travel via the call_options() context manager.",
+        "native_retry": (
+            "aiohttp's one-shot idempotent retry on a dropped keep-alive connection is silenced via the private "
+            "_retry_connection attribute; DEGRADED because the seam is not a public API."
+        ),
+        "seam_bypass": (
+            "Per-request middlewares=() REPLACES session middlewares and bypasses the engine entirely; TraceConfig "
+            "cannot be overridden per request and emits the uninstrumented_calls sentinel when that happens."
+        ),
+        "ceil_threshold": "ClientTimeout.ceil_threshold is raised so aiohttp never ceils deadlines to whole seconds.",
+        "body_duration": "The middleware returns at headers; body read is not instrumented (no body_duration metric).",
+        "max_keepalive": "aiohttp has no cap on the NUMBER of keep-alive connections; pool.max_keepalive is ignored.",
+    },
+)
+
+__all__ = ["CAPABILITIES"]

clientwright/adapters/aiohttp/classify.py

@@ -0,0 +1,59 @@
+"""aiohttp exception -> FailureKind classification.
+
+aiohttp folds pool waiting, DNS, TCP and TLS into one connect phase, so there
+is no POOL_TIMEOUT here (declared as a collapse into CONNECT_TIMEOUT). DNS
+failures, unlike httpx, ARE distinguishable natively.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import ssl
+
+from ...core.model import FailureKind
+from ._imports import aiohttp
+
+
+def _has_ssl_cause(exc: BaseException) -> bool:
+    seen: set[int] = set()
+    current: BaseException | None = exc
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        if isinstance(current, (ssl.SSLError, ssl.CertificateError)):
+            return True
+        current = current.__cause__ or current.__context__
+    return False
+
+
+def classify_error(exc: BaseException) -> FailureKind:
+    if isinstance(exc, asyncio.CancelledError):
+        return FailureKind.CANCELLED
+    if isinstance(exc, aiohttp.ConnectionTimeoutError):
+        return FailureKind.CONNECT_TIMEOUT
+    if isinstance(exc, aiohttp.SocketTimeoutError):
+        return FailureKind.READ_TIMEOUT
+    if isinstance(exc, aiohttp.ServerTimeoutError):
+        return FailureKind.CONNECT_TIMEOUT
+    if isinstance(exc, aiohttp.ClientSSLError):
+        # Covers ClientConnectorCertificateError and ClientConnectorSSLError;
+        # must sit ABOVE ClientConnectorError, which it subclasses in
+        # aiohttp>=3.14 - below it the branch is dead code.
+        return FailureKind.TLS_ERROR
+    if isinstance(exc, aiohttp.ClientConnectorDNSError):
+        return FailureKind.DNS_ERROR
+    if isinstance(exc, aiohttp.ClientConnectorError):
+        return FailureKind.TLS_ERROR if _has_ssl_cause(exc) else FailureKind.CONNECT_ERROR
+    if isinstance(exc, aiohttp.ServerDisconnectedError):
+        return FailureKind.DISCONNECTED
+    if isinstance(exc, aiohttp.ClientOSError):
+        return FailureKind.CONNECT_ERROR
+    if isinstance(exc, aiohttp.ClientPayloadError):
+        return FailureKind.BODY_ERROR
+    if isinstance(exc, aiohttp.ClientResponseError):
+        return FailureKind.PROTOCOL_ERROR
+    if isinstance(exc, TimeoutError):
+        return FailureKind.TOTAL_TIMEOUT
+    return FailureKind.UNKNOWN
+
+
+__all__ = ["classify_error"]

clientwright/adapters/aiohttp/errors.py

@@ -0,0 +1,57 @@
+"""Kernel errors dual-inherited into the aiohttp family.
+
+A user's ``except aiohttp.ClientError`` (or ``except asyncio.TimeoutError``)
+keeps working when clientwright raises on its own authority.
+"""
+
+from __future__ import annotations
+
+from ...core.errors import CallError, CircuitOpenError, DeadlineExceededError, TooManyRedirectsError
+from ._imports import aiohttp
+
+
+class AiohttpCircuitOpenError(CircuitOpenError, aiohttp.ClientError):
+    """Circuit open, catchable as aiohttp.ClientError."""
+
+
+class AiohttpDeadlineExceededError(DeadlineExceededError, aiohttp.ServerTimeoutError):
+    """Total deadline exhausted, catchable as asyncio.TimeoutError and aiohttp.ClientError."""
+
+
+class AiohttpTooManyRedirectsError(TooManyRedirectsError, aiohttp.TooManyRedirects):
+    """Owned redirect limit exceeded, catchable as aiohttp.TooManyRedirects.
+
+    ``ClientResponseError.__init__`` demands request_info/history positionally,
+    which breaks the cooperative super chain - so this class initializes both
+    parents by hand and pins the aiohttp-side attributes its ``__str__`` needs.
+    """
+
+    def __init__(self, hops: int) -> None:
+        Exception.__init__(self, f"Exceeded {hops} redirect hops")
+        self.hops = hops
+        self.request_info = None  # type: ignore[assignment]
+        self.history = ()
+        self.status = 0
+        self.message = f"Exceeded {hops} redirect hops"
+        self.headers = None
+
+    def __str__(self) -> str:
+        return self.message
+
+
+def translate_call_error(error: CallError) -> BaseException:
+    if isinstance(error, CircuitOpenError):
+        return AiohttpCircuitOpenError(error.key, error.retry_after)
+    if isinstance(error, DeadlineExceededError):
+        return AiohttpDeadlineExceededError(error.total)
+    if isinstance(error, TooManyRedirectsError):
+        return AiohttpTooManyRedirectsError(error.hops)
+    return error
+
+
+__all__ = [
+    "AiohttpCircuitOpenError",
+    "AiohttpDeadlineExceededError",
+    "AiohttpTooManyRedirectsError",
+    "translate_call_error",
+]

clientwright/adapters/aiohttp/middleware.py

@@ -0,0 +1,103 @@
+"""The engine-driven client middleware.
+
+The seam sits UNDER the public API: the returned client is a genuine
+``aiohttp.ClientSession`` and every request that flows through it passes the
+engine - unless the caller writes ``middlewares=()``, which aiohttp treats as
+a full replacement; the TraceConfig sentinel counts those bypasses.
+
+The middleware is a long-lived hashable object on purpose: aiohttp caches the
+built middleware chain per ``(handler, middlewares)`` key, so a per-request
+closure would thrash that LRU on every call.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable, Mapping
+
+from ...core.contracts.message import RequestView
+from ...core.engine.aio import AsyncAttemptEngine
+from ._imports import URL, aiohttp
+from .trace import ENGINE_ACTIVE
+from .views import AiohttpRequestView
+
+type ClientHandler = Callable[[aiohttp.ClientRequest], Awaitable[aiohttp.ClientResponse]]
+
+
+class ProxyRouter:
+    """Per-hop proxy choice: explicit URL, or environment proxies by scheme."""
+
+    __slots__ = ("_by_scheme", "_explicit", "_no_proxy_hosts")
+
+    def __init__(
+        self,
+        explicit: str | None,
+        by_scheme: Mapping[str, str] | None = None,
+        no_proxy_hosts: tuple[str, ...] = (),
+    ) -> None:
+        self._explicit = URL(explicit) if explicit is not None else None
+        self._by_scheme = {scheme: URL(url) for scheme, url in (by_scheme or {}).items()}
+        self._no_proxy_hosts = no_proxy_hosts
+
+    def _bypasses(self, host: str) -> bool:
+        for entry in self._no_proxy_hosts:
+            candidate = entry.lstrip(".")
+            if host == candidate or host.endswith("." + candidate):
+                return True
+        return False
+
+    def apply(self, request: aiohttp.ClientRequest) -> None:
+        if self._explicit is not None:
+            request.proxy = self._explicit
+            return
+        host = request.url.host or ""
+        if self._bypasses(host):
+            request.proxy = None
+            return
+        request.proxy = self._by_scheme.get(request.url.scheme)
+
+
+async def _clear_body(request: aiohttp.ClientRequest) -> None:
+    """Drop the body the aiohttp way: ``update_body`` closes the old payload."""
+    update = getattr(request, "update_body", None)
+    if update is None:  # pragma: no cover - update_body exists on aiohttp>=3.12
+        request.body = b""
+        return
+    result = update(b"")
+    if result is not None and hasattr(result, "__await__"):
+        await result
+
+
+class EngineMiddleware:
+    """One logical call per invocation; the engine owns retries, redirects, deadline."""
+
+    __slots__ = ("_engine", "_proxy")
+
+    def __init__(self, engine: AsyncAttemptEngine, proxy: ProxyRouter | None = None) -> None:
+        self._engine = engine
+        self._proxy = proxy
+
+    async def _send(self, view: RequestView, handler: ClientHandler) -> aiohttp.ClientResponse:
+        native = view.native
+        if isinstance(view, AiohttpRequestView) and view.pending_empty_body:
+            await _clear_body(native)
+            view.pending_empty_body = False
+        if self._proxy is not None:
+            # Inside the engine seam: every owned-redirect hop re-routes.
+            self._proxy.apply(native)
+        return await handler(native)
+
+    async def __call__(self, request: aiohttp.ClientRequest, handler: ClientHandler) -> aiohttp.ClientResponse:
+        token = ENGINE_ACTIVE.set(True)
+        try:
+
+            async def send(view: RequestView) -> aiohttp.ClientResponse:
+                return await self._send(view, handler)
+
+            response = await self._engine.run(request, send)
+            assert isinstance(response, aiohttp.ClientResponse)
+            return response
+        finally:
+            ENGINE_ACTIVE.reset(token)
+
+
+__all__ = ["EngineMiddleware", "ProxyRouter"]