asyncly 0.6.2__tar.gz → 0.7.0__tar.gz

{asyncly-0.6.2 → asyncly-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: asyncly
-Version: 0.6.2
+Version: 0.7.0
 Summary: Simple HTTP client and server for your integrations based on aiohttp
 Project-URL: Homepage, https://github.com/andy-takker/asyncly
 Project-URL: Source, https://github.com/andy-takker/asyncly
@@ -383,6 +383,69 @@ Pass an ``ssl.SSLContext`` to ``start_service`` to serve over HTTPS.
    async with start_service(routes, ssl_context=ctx) as service:
        ...
 
+Testing through a proxy
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``BaseHttpClient`` accepts ``proxy`` and ``proxy_auth`` (forwarded to aiohttp_).
+Set them once on the client, or override per request:
+
+.. code-block:: python
+
+   from aiohttp import BasicAuth, ClientSession
+   from asyncly import BaseHttpClient
+
+   async with ClientSession() as session:
+       client = CatfactClient(
+           url=url,
+           session=session,
+           client_name="catfact",
+           proxy="http://127.0.0.1:8080",
+           proxy_auth=BasicAuth("user", "secret"),
+       )
+
+To test that a client genuinely routes through a proxy, ``start_proxy`` spins
+up an in-process forwarding HTTP proxy. It records every request passing
+through it and forwards it to the real target (typically another
+``start_service``). Pair it with the ``mock_proxy`` fixture or use it directly:
+
+.. code-block:: python
+
+   from aiohttp import BasicAuth, ClientSession
+   from asyncly.srvmocker import (
+       JsonResponse,
+       MockRoute,
+       start_proxy,
+       start_service,
+   )
+
+   async def test_routes_through_proxy() -> None:
+       routes = [MockRoute("GET", "/fact", "fact")]
+       async with start_service(routes) as target:
+           target.register("fact", JsonResponse({"fact": "ok"}))
+           async with start_proxy(auth=BasicAuth("user", "secret")) as proxy:
+               async with ClientSession() as s:
+                   resp = await s.get(
+                       target.url / "fact",
+                       proxy=proxy.url,
+                       proxy_auth=BasicAuth("user", "secret"),
+                   )
+                   assert (await resp.json()) == {"fact": "ok"}
+
+           proxy.assert_called(times=1, method="GET")
+
+``MockProxyService`` mirrors ``MockService``'s assertion helpers, reading from
+the recorded history of forwarded requests:
+
+- ``get_calls() -> list[RequestHistory]``
+- ``last_call() -> RequestHistory`` (raises ``AssertionError`` if empty)
+- ``assert_called(*, times=, target=, method=, json=, body=, headers=, query=)``
+- ``assert_not_called()``
+
+When ``start_proxy(auth=...)`` is set, requests missing or carrying a wrong
+``Proxy-Authorization`` header get a ``407 Proxy Authentication Required`` and
+are **not** forwarded. Only plain HTTP targets are supported (no ``CONNECT`` /
+HTTPS tunnelling).
+
 .. _PyPI: https://pypi.org/
 .. _aiohttp: https://pypi.org/project/aiohttp/
 .. _msgpack: https://msgpack.org

{asyncly-0.6.2 → asyncly-0.7.0}/README.rst

@@ -339,6 +339,69 @@ Pass an ``ssl.SSLContext`` to ``start_service`` to serve over HTTPS.
    async with start_service(routes, ssl_context=ctx) as service:
        ...
 
+Testing through a proxy
+~~~~~~~~~~~~~~~~~~~~~~~
+
+``BaseHttpClient`` accepts ``proxy`` and ``proxy_auth`` (forwarded to aiohttp_).
+Set them once on the client, or override per request:
+
+.. code-block:: python
+
+   from aiohttp import BasicAuth, ClientSession
+   from asyncly import BaseHttpClient
+
+   async with ClientSession() as session:
+       client = CatfactClient(
+           url=url,
+           session=session,
+           client_name="catfact",
+           proxy="http://127.0.0.1:8080",
+           proxy_auth=BasicAuth("user", "secret"),
+       )
+
+To test that a client genuinely routes through a proxy, ``start_proxy`` spins
+up an in-process forwarding HTTP proxy. It records every request passing
+through it and forwards it to the real target (typically another
+``start_service``). Pair it with the ``mock_proxy`` fixture or use it directly:
+
+.. code-block:: python
+
+   from aiohttp import BasicAuth, ClientSession
+   from asyncly.srvmocker import (
+       JsonResponse,
+       MockRoute,
+       start_proxy,
+       start_service,
+   )
+
+   async def test_routes_through_proxy() -> None:
+       routes = [MockRoute("GET", "/fact", "fact")]
+       async with start_service(routes) as target:
+           target.register("fact", JsonResponse({"fact": "ok"}))
+           async with start_proxy(auth=BasicAuth("user", "secret")) as proxy:
+               async with ClientSession() as s:
+                   resp = await s.get(
+                       target.url / "fact",
+                       proxy=proxy.url,
+                       proxy_auth=BasicAuth("user", "secret"),
+                   )
+                   assert (await resp.json()) == {"fact": "ok"}
+
+           proxy.assert_called(times=1, method="GET")
+
+``MockProxyService`` mirrors ``MockService``'s assertion helpers, reading from
+the recorded history of forwarded requests:
+
+- ``get_calls() -> list[RequestHistory]``
+- ``last_call() -> RequestHistory`` (raises ``AssertionError`` if empty)
+- ``assert_called(*, times=, target=, method=, json=, body=, headers=, query=)``
+- ``assert_not_called()``
+
+When ``start_proxy(auth=...)`` is set, requests missing or carrying a wrong
+``Proxy-Authorization`` header get a ``407 Proxy Authentication Required`` and
+are **not** forwarded. Only plain HTTP targets are supported (no ``CONNECT`` /
+HTTPS tunnelling).
+
 .. _PyPI: https://pypi.org/
 .. _aiohttp: https://pypi.org/project/aiohttp/
 .. _msgpack: https://msgpack.org

{asyncly-0.6.2 → asyncly-0.7.0}/asyncly/client/base.py

@@ -1,6 +1,6 @@
 from typing import Any
 
-from aiohttp import ClientSession
+from aiohttp import BasicAuth, ClientSession
 from aiohttp.client import DEFAULT_TIMEOUT
 from yarl import URL
 
@@ -13,18 +13,28 @@ from asyncly.client.typing import MethodType
 
 
 class BaseHttpClient:
-    __slots__ = ("_url", "_session", "_client_name")
+    __slots__ = ("_url", "_session", "_client_name", "_proxy", "_proxy_auth")
 
     _url: URL
     _session: ClientSession
     _client_name: str
+    _proxy: URL | None
+    _proxy_auth: BasicAuth | None
 
     def __init__(
-        self, url: URL | str, session: ClientSession, client_name: str
+        self,
+        url: URL | str,
+        session: ClientSession,
+        client_name: str,
+        *,
+        proxy: URL | str | None = None,
+        proxy_auth: BasicAuth | None = None,
     ) -> None:
         self._url = url if isinstance(url, URL) else URL(url)
         self._session = session
         self._client_name = client_name
+        self._proxy = URL(proxy) if isinstance(proxy, str) else proxy
+        self._proxy_auth = proxy_auth
 
     @property
     def url(self) -> URL:
@@ -38,6 +48,10 @@ class BaseHttpClient:
         timeout: TimeoutType = DEFAULT_TIMEOUT,
         **kwargs: Any,
     ) -> Any:
+        if "proxy" not in kwargs and self._proxy is not None:
+            kwargs["proxy"] = self._proxy
+        if "proxy_auth" not in kwargs and self._proxy_auth is not None:
+            kwargs["proxy_auth"] = self._proxy_auth
         async with self._session.request(
             method=method,
             url=url,

{asyncly-0.6.2 → asyncly-0.7.0}/asyncly/client/metrics/instrumentable_client.py

@@ -3,7 +3,7 @@ from time import perf_counter
 from types import TracebackType
 from typing import Any
 
-from aiohttp import ClientResponse, ClientSession
+from aiohttp import BasicAuth, ClientResponse, ClientSession
 from aiohttp.client import DEFAULT_TIMEOUT
 from yarl import URL
 
@@ -16,15 +16,24 @@ from asyncly.client.typing import ResponseHandler, ResponseHandlersType, RouteRe
 
 
 class InstrumentableHttpClient(BaseHttpClient):
-    __slots__ = ("_metrics_sink", "_resolve_route") + BaseHttpClient.__slots__
+    __slots__ = ("_metrics_sink", "_resolve_route")
 
     def __init__(
         self,
         url: URL | str,
         session: ClientSession,
         client_name: str,
+        *,
+        proxy: URL | str | None = None,
+        proxy_auth: BasicAuth | None = None,
     ) -> None:
-        super().__init__(url=url, session=session, client_name=client_name)
+        super().__init__(
+            url=url,
+            session=session,
+            client_name=client_name,
+            proxy=proxy,
+            proxy_auth=proxy_auth,
+        )
         self._metrics_sink: MetricsSink = NoopSink()
         self._resolve_route: RouteResolver = default_route_resolver
 

{asyncly-0.6.2 → asyncly-0.7.0}/asyncly/pytest_plugin.py

@@ -18,6 +18,7 @@ import pytest
 
 if TYPE_CHECKING:
     from asyncly.srvmocker.models import MockRoute, MockService
+    from asyncly.srvmocker.proxy import MockProxyService
 
 
 @pytest.fixture
@@ -34,3 +35,12 @@ async def mock_service(
 
     async with start_service(mock_routes) as service:
         yield service
+
+
+@pytest.fixture
+async def mock_proxy() -> "AsyncIterator[MockProxyService]":
+    """A forwarding mock proxy; point a client at it via ``proxy=mock_proxy.url``."""
+    from asyncly.srvmocker import start_proxy
+
+    async with start_proxy() as proxy:
+        yield proxy

{asyncly-0.6.2 → asyncly-0.7.0}/asyncly/srvmocker/__init__.py

@@ -5,6 +5,7 @@ from asyncly.srvmocker.exceptions import (
 )
 from asyncly.srvmocker.matching import Match
 from asyncly.srvmocker.models import MockRoute, MockService
+from asyncly.srvmocker.proxy import MockProxyService, start_proxy
 from asyncly.srvmocker.responses.base import BaseMockResponse
 from asyncly.srvmocker.responses.content import ContentResponse
 from asyncly.srvmocker.responses.json import JsonResponse
@@ -17,6 +18,7 @@ __all__ = (
     "ContentResponse",
     "JsonResponse",
     "Match",
+    "MockProxyService",
     "MockRoute",
     "MockService",
     "RawResponse",
@@ -24,5 +26,6 @@ __all__ = (
     "SequenceResponse",
     "SrvMockerError",
     "UnknownHandlerError",
+    "start_proxy",
     "start_service",
 )

{asyncly-0.6.2 → asyncly-0.7.0}/asyncly/srvmocker/models.py

@@ -1,7 +1,7 @@
 from collections.abc import MutableMapping, MutableSequence
 from dataclasses import dataclass
 
-from aiohttp.web_request import Request
+from aiohttp.web_request import BaseRequest
 from yarl import URL
 
 from asyncly.srvmocker.matching import Match
@@ -18,7 +18,7 @@ class MockRoute:
 
 @dataclass
 class RequestHistory:
-    request: Request
+    request: BaseRequest
     body: bytes
 
 

asyncly-0.7.0/asyncly/srvmocker/proxy.py

@@ -0,0 +1,164 @@
+"""In-process forwarding HTTP proxy for tests.
+
+`start_proxy` spins up a real forward proxy (via aiohttp's ``RawTestServer``)
+that records every request passing through it and forwards it to the absolute
+target URL the client requested.  Combined with :func:`start_service` it lets
+you test that a client genuinely routes through a proxy::
+
+    async with start_service([MockRoute("GET", "/x", "ok")]) as target:
+        target.register("ok", JsonResponse({"ok": True}))
+        async with start_proxy() as proxy:
+            async with ClientSession() as s:
+                resp = await s.get(target.url / "x", proxy=proxy.url)
+            proxy.assert_called(times=1, method="GET")
+
+Only plain HTTP targets are supported (no ``CONNECT`` / HTTPS tunnelling).
+"""
+
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from http import HTTPStatus
+
+from aiohttp import BasicAuth, ClientSession
+from aiohttp.test_utils import RawTestServer
+from aiohttp.web_request import BaseRequest
+from aiohttp.web_response import Response
+from multidict import CIMultiDict, CIMultiDictProxy
+from yarl import URL
+
+from asyncly.srvmocker.assertions import call_matches
+from asyncly.srvmocker.models import RequestHistory
+
+# Hop-by-hop headers must not be forwarded end-to-end (RFC 9110 section 7.6.1),
+# plus the proxy-specific ones.
+_HOP_BY_HOP = frozenset(
+    h.lower()
+    for h in (
+        "connection",
+        "keep-alive",
+        "proxy-authenticate",
+        "proxy-authorization",
+        "proxy-connection",
+        "te",
+        "trailer",
+        "transfer-encoding",
+        "upgrade",
+        "host",
+    )
+)
+# On the response we additionally drop Content-Length so aiohttp recomputes it
+# from the (verbatim) body we relay.
+_HOP_BY_HOP_RESPONSE = _HOP_BY_HOP | frozenset({"content-length"})
+
+
+@dataclass(frozen=True)
+class MockProxyService:
+    url: URL
+    history: list[RequestHistory] = field(default_factory=list)
+
+    def set_url(self, url: URL) -> None:
+        object.__setattr__(self, "url", url)
+
+    def get_calls(self) -> list[RequestHistory]:
+        return list(self.history)
+
+    def last_call(self) -> RequestHistory:
+        if not self.history:
+            raise AssertionError("no requests recorded by proxy")
+        return self.history[-1]
+
+    def assert_called(
+        self,
+        *,
+        times: int | None = None,
+        target: URL | str | None = None,
+        method: str | None = None,
+        json: object = None,
+        body: bytes | None = None,
+        headers: dict[str, str] | None = None,
+        query: dict[str, str] | None = None,
+    ) -> None:
+        calls = self.get_calls()
+        if times is not None and len(calls) != times:
+            raise AssertionError(f"proxy: expected {times} call(s), got {len(calls)}")
+        criteria = (target, method, json, body, headers, query)
+        if times is not None and all(v is None for v in criteria):
+            return
+        if not calls:
+            raise AssertionError("proxy: expected at least one call, got 0")
+        for call in calls:
+            if target is not None and str(call.request.url) != str(URL(target)):
+                continue
+            if method is not None and call.request.method != method:
+                continue
+            if call_matches(call, json=json, body=body, headers=headers, query=query):
+                return
+        raise AssertionError(
+            f"proxy: none of {len(calls)} call(s) matched the given criteria"
+        )
+
+    def assert_not_called(self) -> None:
+        if self.history:
+            raise AssertionError(f"proxy: expected no calls, got {len(self.history)}")
+
+
+def _relay_headers(
+    source: CIMultiDictProxy[str], *, drop: frozenset[str]
+) -> CIMultiDict[str]:
+    """Copy headers preserving duplicates (e.g. multiple ``Set-Cookie``)."""
+    relayed: CIMultiDict[str] = CIMultiDict()
+    for key, value in source.items():
+        if key.lower() not in drop:
+            relayed.add(key, value)
+    return relayed
+
+
+@asynccontextmanager
+async def start_proxy(
+    *,
+    auth: BasicAuth | None = None,
+) -> AsyncGenerator[MockProxyService, None]:
+    proxy = MockProxyService(url=URL())
+    expected_auth = auth.encode() if auth is not None else None
+
+    # Relay target responses verbatim (HTTP, uncompressed): keep the body and
+    # its Content-Encoding untouched instead of auto-decompressing.
+    forward_session = ClientSession(auto_decompress=False)
+
+    async def _handler(request: BaseRequest) -> Response:
+        body = await request.read()
+        proxy.history.append(RequestHistory(request=request, body=body))
+
+        if expected_auth is not None:
+            provided = request.headers.get("Proxy-Authorization")
+            if provided != expected_auth:
+                return Response(
+                    status=HTTPStatus.PROXY_AUTHENTICATION_REQUIRED,
+                    reason="Proxy Authentication Required",
+                    headers={"Proxy-Authenticate": "Basic"},
+                )
+
+        async with forward_session.request(
+            method=request.method,
+            url=request.url,
+            headers=_relay_headers(request.headers, drop=_HOP_BY_HOP),
+            data=body or None,
+            allow_redirects=False,
+        ) as upstream:
+            payload = await upstream.read()
+            return Response(
+                status=upstream.status,
+                reason=upstream.reason,
+                headers=_relay_headers(upstream.headers, drop=_HOP_BY_HOP_RESPONSE),
+                body=payload,
+            )
+
+    server = RawTestServer(_handler)
+    try:
+        await server.start_server()
+        proxy.set_url(server.make_url(""))
+        yield proxy
+    finally:
+        await server.close()
+        await forward_session.close()

{asyncly-0.6.2 → asyncly-0.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "asyncly"
-version = "0.6.2"
+version = "0.7.0"
 description = "Simple HTTP client and server for your integrations based on aiohttp"
 authors = [{ name = "Sergey Natalenko", email = "sergey.natalenko@mail.ru" }]
 requires-python = ">=3.10, <4"