.. _micro.web.middleware:


Middlewares
===========


.. highlight:: python

.. currentmodule:: micro.web.middleware

.. note::

   This topic describes middleware support in Micro.Web

Concept
-------

The aim of middleware design in Micro.Web is to provide framework for writing isolated, consistent and testable middlewares.
Instead of traditional wsgi-like approach, which, for example, aiohttp provide, Micro.Web middlewares are inspired by
`Django middlewares`_ .

This way, each middleware declares several *hooks*, which are invoked in process of request
handling.

User-defined middlewares should inherit base class :class:`Middleware`, and re-define its methods for
custom processing of the hooks.

The middleware hooks should return None. If the hook return
the subclass of :class:`aiohttp.web_reqrep.StreamResponse`, this terminates middleware processing flow, and the response
will bypass all other middleware hooks except response hook, which is invoked for every response.

See :ref:`micro.core.middleware_reference` for details.


Hooks
-----
This describes the hooks which are invoked during request handling flow.

Request hook
^^^^^^^^^^^^

.. function:: request(request)

    :param request: An incoming request instance.
    :type request: micro.web.request.Request
    :return: None or response to write

Request hook is invoked right after the request initialization, before routing call. Every request to Micro.Web will
pass this hook, even if there is no route to match it.

Route match hook
^^^^^^^^^^^^^^^^

.. function:: match_info(request)

    :param request: An incoming request instance.
    :type request: :class:`micro.web.request.Request`
    :param match_info: An aiohttp`s match info object
    :type match_info: aiohttp.web_urldispatcher.UrlMappingMatchInfo
    :return: None or response to write

Request hook nvoked right after the routing initialization, if the matching route is found. This hook will be executed
only for requests for valid routes (i.e. that which declared by the application)

Response hook
^^^^^^^^^^^^^

.. function:: response(request, response, result)

    :param request: An incoming request instance
    :type request: :class:`micro.web.request.Request`
    :param response: An outcoming response instance, StreamResponse subclass
    :type response: :class:`aiohttp.web_reqrep.StreamResponse`
    :param result: A result of request handler, simply the return value of the handler function or any middleware processing hooks.
    :return: None or response to write

Response hook invoked for every response.

Exception hook
^^^^^^^^^^^^^^

.. function:: response(request)

    :param request: An incoming request instance
    :type request: :class:`micro.web.request.Request`
    :param exception: An exception instance
    :type exception: :class:`Exception`
    :return: None or response to write

Processes the exception happened during the request handling.

Installation
------------
Middlewares can be enabled globally (for any request handler), or just for particular endpoints.

Function for installing global middlewares:

.. autofunction:: install_global

.. autofunction:: install_for_endpoint

Also, there is convenient  :ref:`micro.core.decorators_reference`

.. _Django middlewares: https://docs.djangoproject.com/en/1.8/topics/http/middleware/