.. currentmodule:: aiohttp

.. _aiohttp-client-middleware-cookbook:

Client Middleware Cookbook
==========================

This cookbook provides examples of how client middlewares can be used for common use cases.

Simple Retry Middleware
-----------------------

It's very easy to create middlewares that can retry a connection on a given condition:

.. literalinclude:: code/client_middleware_cookbook.py
   :pyobject: retry_middleware

.. warning::

    It is recommended to ensure loops are bounded (e.g. using a ``for`` loop) to avoid
    creating an infinite loop.

Logging to an external service
------------------------------

If we needed to log our requests via an API call to an external server or similar, we could
create a simple middleware like this:

.. literalinclude:: code/client_middleware_cookbook.py
   :pyobject: api_logging_middleware

.. warning::

    Using the same session from within a middleware can cause infinite recursion if
    that request gets processed again by the middleware.

    To avoid such recursion a middleware should typically make requests with
    ``middlewares=()`` or else contain some condition to stop the request triggering
    the same logic when it is processed again by the middleware (e.g by whitelisting
    the API domain of the request).

Token Refresh Middleware
------------------------

If you need to refresh access tokens to continue accessing an API, this is also a good
candidate for a middleware. For example, you could check for a 401 response, then
refresh the token and retry:

.. literalinclude:: code/client_middleware_cookbook.py
   :pyobject: TokenRefresh401Middleware

If you have an expiry time for the token, you could refresh at the expiry time, to avoid the
failed request:

.. literalinclude:: code/client_middleware_cookbook.py
   :pyobject: TokenRefreshExpiryMiddleware

Or you could even refresh preemptively in a background task to avoid any API delays. This is probably more
efficient to implement without a middleware:

.. literalinclude:: code/client_middleware_cookbook.py
   :pyobject: token_refresh_preemptively_example
   :lines: 2-
   :dedent:

Or combine the above approaches to create a more robust solution.

.. note::

    These can also be adjusted to handle proxy auth by modifying
    :attr:`ClientRequest.proxy_headers`.

Server-side Request Forgery Protection
--------------------------------------

To provide protection against server-side request forgery, we could blacklist any internal
IPs or domains. We could create a middleware that rejects requests made to a blacklist:

.. literalinclude:: code/client_middleware_cookbook.py
   :pyobject: ssrf_middleware

.. warning::

   The above example is simplified for demonstration purposes. A production-ready
   implementation should also check IPv6 addresses (``::1``), private IP ranges,
   link-local addresses, and other internal hostnames. Consider using a well-tested
   library for SSRF protection in production environments.

If you know that your services correctly reject requests with an incorrect `Host` header, then
that may provide sufficient protection. Otherwise, we still have a concern with an attacker's
own domain resolving to a blacklisted IP. To provide complete protection, we can also
create a custom resolver:

.. literalinclude:: code/client_middleware_cookbook.py
   :pyobject: SSRFConnector

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,
   authentication before retry, etc.

3. **Avoid infinite recursion**: When making HTTP requests inside middleware, either:

   - Use ``middlewares=()`` to disable middleware for internal requests
   - Check the request URL/host to skip middleware for specific endpoints
   - Use a separate session for internal requests

4. **Handle errors gracefully**: Don't let middleware errors break the request flow unless
   absolutely necessary.

5. **Use bounded loops**: Always use ``for`` loops with a maximum iteration count instead
   of unbounded ``while`` loops to prevent infinite retries.

6. **Consider performance**: Each middleware adds overhead. For simple cases like adding
   static headers, consider using session or request parameters instead.

7. **Test thoroughly**: Middleware can affect all requests in subtle ways. Test edge cases
   like network errors, timeouts, and concurrent requests.

See Also
--------

- :ref:`aiohttp-client-middleware` - Core middleware documentation
- :ref:`aiohttp-client-advanced` - Advanced client usage
- :class:`DigestAuthMiddleware` - Built-in digest authentication middleware