============
Architecture
============

Adapters
--------

Adapters are the core engine of ``lightreq``. They define how an HTTP request is dispatched.

- **UrllibAdapter** (``"urllib"``): Ideal for environments where external dependencies are strictly prohibited.
- **RequestsAdapter** (``"requests"``): Ideal for more complex applications requiring connection pooling or advanced session persistence.

The adapter system is designed to be extensible, with planned support for ``aiohttp`` and ``httpx``.

Middleware
----------

Middlewares act as wrappers around your core request handler. They are executed in a chain,
allowing them to intercept and modify the ``Request`` object before it is sent, or the ``Response``
object before it is returned to the client.

A simple example of a custom middleware:

.. code-block:: python

   def my_custom_middleware(next_handler):
       def handler(request):
           # Do something before the request is sent
           print("Sending request to:", request.url)

           # Pass to the next handler/middleware
           response = next_handler(request)

           # Do something with the response
           print("Received status code:", response.status_code)

           return response
       return handler

.. warning::

   The order of middleware matters. Middlewares are executed in the order they are defined.
   For example, placing ``retry`` before ``logging`` ensures that each retry attempt is logged::

      logging middleware -> retry middleware -> adapter (actual HTTP request)

.. note::

   This is just a brief overview. For the full middleware guide such as including all built-in
   middlewares, ordering rules, cookbook recipes, and how to write your own middleware, please see
   :doc:`middleware`.