diff --git a/docs/client_middleware_cookbook.rst b/docs/client_middleware_cookbook.rst index 33994160fba..e890b02a4bf 100644 --- a/docs/client_middleware_cookbook.rst +++ b/docs/client_middleware_cookbook.rst @@ -98,6 +98,29 @@ Using both of these together in a session should provide full SSRF protection. Best Practices -------------- +.. important:: + + **Request-level middlewares replace session middlewares**: When you pass ``middlewares`` + to ``request()`` or its convenience methods (``get()``, ``post()``, etc.), it completely + replaces the session-level middlewares, rather than extending them. This differs from + other parameters like ``headers``, which are merged. + + .. code-block:: python + + session = ClientSession(middlewares=[middleware_session]) + + # Session middleware is used + await session.get("http://example.com") + + # Session middleware is NOT used, only request middleware + await session.get("http://example.com", middlewares=[middleware_request]) + + # To use both, explicitly pass both + await session.get( + "http://example.com", + middlewares=[middleware_session, middleware_request] + ) + 1. **Keep middleware focused**: Each middleware should have a single responsibility. 2. **Order matters**: Middlewares execute in the order they're listed. Place logging first,