✨ Support middleware to wrap httpx.send calls.

ChangeLog.md

@@ -11,6 +11,7 @@ and the format of this file is based on [Keep a Changelog](https://keepachangelo
 ### Added
 - Accept session_factory in `ClientBase.__init__`.
 - Helper function to iterate over pages.
+- Accept middleware.
 
 ### Fixed
 - Handling collections in request bodies.

src/lapidary/runtime/__init__.py

@@ -8,6 +8,7 @@
     'FormExplode',
     'Header',
     'HttpErrorResponse',
+    'HttpxMiddleware',
     'LapidaryError',
     'LapidaryResponseError',
     'Metadata',
@@ -35,6 +36,7 @@
 
 from .annotations import Body, Cookie, Header, Metadata, Path, Query, Response, Responses, StatusCode
 from .client_base import ClientBase, lapidary_user_agent
+from .middleware import HttpxMiddleware
 from .model import ModelBase
 from .model.error import HttpErrorResponse, LapidaryError, LapidaryResponseError, UnexpectedResponse
 from .model.param_serialization import Form, FormExplode, SimpleMultimap, SimpleString

src/lapidary/runtime/client_base.py

@@ -7,11 +7,12 @@
 import typing_extensions as typing
 
 from .http_consts import USER_AGENT
+from .middleware import HttpxMiddleware
 from .model.auth import AuthRegistry
 
 if typing.TYPE_CHECKING:
     import types
-    from collections.abc import Iterable
+    from collections.abc import Iterable, Sequence
 
     from .types_ import ClientArgs, NamedAuth, SecurityRequirements, SessionFactory
 
@@ -29,13 +30,15 @@ def __init__(
         self,
         security: Iterable[SecurityRequirements] | None = None,
         session_factory: SessionFactory = httpx.AsyncClient,
+        middlewares: Sequence[HttpxMiddleware] = (),
         **httpx_kwargs: typing.Unpack[ClientArgs],
     ) -> None:
         self._client = session_factory(**httpx_kwargs)
         if USER_AGENT not in self._client.headers:
             self._client.headers[USER_AGENT] = lapidary_user_agent()
 
         self._auth_registry = AuthRegistry(security)
+        self._middlewares = middlewares
 
     async def __aenter__(self: typing.Self) -> typing.Self:
         await self._client.__aenter__()

src/lapidary/runtime/middleware.py

@@ -0,0 +1,15 @@
+import abc
+from typing import Generic, TypeVar
+
+import httpx
+
+State = TypeVar('State')
+
+
+class HttpxMiddleware(Generic[State]):
+    @abc.abstractmethod
+    async def handle_request(self, request: httpx.Request) -> State:
+        pass
+
+    async def handle_response(self, response: httpx.Response, request: httpx.Request, state: State) -> None:
+        pass

src/lapidary/runtime/model/op.py

@@ -31,9 +31,17 @@ def mk_exchange_fn(
     async def exchange(self: 'ClientBase', **kwargs) -> typing.Any:
         request, auth = request_adapter.build_request(self, kwargs)
 
+        mw_state = []
+        for mw in self._middlewares:
+            mw_state.append(await mw.handle_request(request))
+
         response = await self._client.send(request, auth=auth)
 
         await response.aread()
+
+        for mw, state in zip(reversed(self._middlewares), reversed(mw_state)):
+            await mw.handle_response(response, request, state)
+
         status_code, result = response_handler.handle_response(response)
         if status_code >= 400:
             raise HttpErrorResponse(status_code, result[1], result[0])

src/lapidary/runtime/paging.py

@@ -1,7 +1,7 @@
 from collections.abc import AsyncIterable, Awaitable, Callable
 from typing import Optional, TypeVar
 
-from typing_extensions import ParamSpec, Unpack
+from typing_extensions import ParamSpec
 
 P = ParamSpec('P')
 R = TypeVar('R')