Intergiciels (« Middleware »)

Les intergiciels représentent un système de points d’entrée dans le traitement des requêtes et des réponses de Django. C’est un système de greffons léger et de bas niveau pour modifier de façon globale les entrées et sorties HTTP de Django.

Chaque composant d’intergiciel est responsable d’effectuer une tâche spécifique. Par exemple, Django contient un intergiciel, AuthenticationMiddleware, qui associe les utilisateurs aux requêtes et aux sessions.

Ce document explique comment fonctionnent les intergiciels, la manière de les activer et d’écrire vos propres intergiciels. Django est livré avec quelques intergiciels intégrés qu’il est possible d’utiliser tels quels. Ils sont documentés dans la référence des intergiciels intégrés.

Écriture de son propre intergiciel

Une fabrique d’intergiciel est un objet exécutable acceptant un exécutable get_response et renvoyant un intergiciel. Un intergiciel est un objet exécutable acceptant une requête et renvoyant une réponse, tout comme une vue.

Un intergiciel peut être écrit comme une fonction qui ressemble à ceci :

def simple_middleware(get_response):
    # One-time configuration and initialization.

    def middleware(request):
        # Code to be executed for each request before
        # the view (and later middleware) are called.

        response = get_response(request)

        # Code to be executed for each request/response after
        # the view is called.

        return response

    return middleware

Ou il peut être écrit comme une classe dont les instances peuvent être appelées, comme ceci :

class SimpleMiddleware:
    def __init__(self, get_response):
        self.get_response = get_response
        # One-time configuration and initialization.

    def __call__(self, request):
        # Code to be executed for each request before
        # the view (and later middleware) are called.

        response = self.get_response(request)

        # Code to be executed for each request/response after
        # the view is called.

        return response

L’exécutable get_response fournit par Django pourrait être la vue elle-même (s’il s’agit du dernier intergiciel) ou alors le prochain intergiciel dans la chaîne. L’intergiciel actuel n’a pas besoin de savoir ou de se préoccuper de ce que c’est exactement, il lui suffit de savoir que ça représente ce qui vient ensuite.

Nous avons un peu simplifié l’explication ci-dessus, car l’exécutable get_response du dernier intergiciel dans la chaîne est en fait une méthode enveloppant la vue, créée par le gestionnaire se chargeant d’appliquer les intergiciels de vue; cette méthode appelle la vue avec les paramètres appropriés et applique les intergiciels template-response et exception.

Un intergiciel peut soit uniquement prendre en charge le code Python synchrone (par défaut), soit uniquement du code asynchrone, ou encore les deux. Consultez Gestion du code asynchrone pour des détails sur la manière d’informer sur ce qui est pris en charge et pour connaître le genre de requête que vous obtenez.

Les intergiciels peuvent se trouver n’importe où dans votre chemin Python.

__init__(get_response)

Les fabriques d’intergiciel doivent accepter un paramètre get_response. Il est aussi possible d’initialiser de l’état global pour l’intergiciel. Gardez à l’esprit quelques précautions :

  • Django initialise les intergiciels avec le seul paramètre get_response, il n’est donc pas possible de définir d’autres paramètres obligatoires à __init__().
  • Contrairement à la méthode __call__() qui est appelée une fois par requête, __init__() n’est appelée qu”une seule fois, lorsque le serveur web démarre.

Signalement d’un intergiciel à exclure

Il est parfois utile de déterminer au moment du démarrage si un intergiciel doit être utilisé. Dans ces cas, la méthode __init__() de l’intergiciel peut générer l’exception MiddlewareNotUsed. Django se charge alors d’enlever cet intergiciel du processus des intergiciels et jouranlise un message de débogage vers le journaliseur django.request lorsque DEBUG vaut True.

Activation des intergiciels

Pour activer un intergiciel, ajoutez son chemin dans la liste MIDDLEWARE de vos réglages Django.

Dans MIDDLEWARE, chaque intergiciel est représenté par une chaîne : le chemin Python complet vers le nom de la classe ou de la fonction de fabrique d’intergiciel. Par exemple, voici la valeur par défaut créée par django-admin startproject:

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.auth.middleware.AuthenticationMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    "django.middleware.clickjacking.XFrameOptionsMiddleware",
]

Une installation de Django n’a pas nécessairement des intergiciels, MIDDLEWARE pouvant très bien être vide si vous le souhaitez, mais il est fortement recommandé d’utiliser au moins CommonMiddleware.

L’ordre dans MIDDLEWARE a son importance car un intergiciel peut dépendre d’un autre. Par exemple, AuthenticationMiddleware stocke l’utilisateur non authentifié dans la session ; il doit donc être exécuté après SessionMiddleware. Voir Ordre des intergiciels pour d’autres indications utiles concernant l’ordre des classes d’intergiciel de Django.

Ordre des intergiciels et empilement

Durant la phase de requête, avant d’appeler la vue, Django applique les intergiciels dans l’ordre où ils sont définis dans MIDDLEWARE, de haut en bas.

Vous pouvez l’imaginer comme un oignon : chaque classe d’intergiciel est une « couche » qui enveloppe la vue, elle-même le cœur de l’oignon. Si la requête traverse toutes les couches de l’oignon (chacune appelant get_response pour passer la requête à la prochaine couche), jusqu’à atteindre la vue au cœur, la réponse va ensuite traverser elle-même toutes les couches (dans l’ordre inverse) jusqu’à sa sortie du mécanisme.

Si l’une des couches décide de court-circuiter et de renvoyer une réponse sans jamais appeler get_response, aucune des couches de l’oignon plus à l’intérieur de cette couche (y compris la vue) ne verra la requête ou la réponse. La réponse ne traversera toujours que les mêmes couches traversées par la requête.

Autres points d’entrée d’intergiciel

En dehors du modèle basique requête/réponse d’intergiciel présenté précédemment, vous pouvez ajouter trois autres méthodes spéciales aux intergiciels basés sur des classes :

process_view()

process_view(request, view_func, view_args, view_kwargs)

request est un objet HttpRequest. view_func et la fonction python que Django s’apprête à utiliser (il s’agit bien de l’objet fonction, pas du nom textuel de la fonction). view_args est une liste de paramètres positionnels qui seront transmis à la vue, et view_kwargs est un dictionnaire de paramètres nommés qui seront transmis à la vue. Ni view_args ni view_kwargs ne comprennent le premier paramètre de la vue (request).

process_view() est appelée juste avant que Django n’appelle la vue.

Elle doit renvoyer soit None, soit un objet HttpResponse. Si elle renvoie None, Django continue le traitement de la requête, en appliquant d’éventuels autres intergiciels process_view(), puis exécute la vue appropriée. Si elle renvoie un objet HttpResponse, Django ne prend pas la peine d’appeler la vue correspondante ; il va simplement appliquer les intergiciels de réponse à cet objet HttpResponse et renvoyer le résultat.

Note

L’accès à request.POST depuis un intergiciel avant que la vue ne soit exécutée ou dans process_view() empêche toute vue exécutée après les intergiciels de pouvoir modifier les gestionnaires de téléversement de la requête, et devrait donc être évité.

La classe CsrfViewMiddleware peut être considérée comme une exception, car elle fournit les décorateurs csrf_exempt() et csrf_protect() qui permettent aux vues de contrôler explicitement le moment de la validation CSRF.

process_exception()

process_exception(request, exception)

request est un objet HttpRequest. exception est un objet Exception généré par la fonction de vue.

Django appelle process_exception() lorsqu’une vue génère une exception. process_exception() doit renvoyer None ou un objet HttpResponse. Si elle renvoie un objet HttpResponse, les intergiciels de réponse par gabarit et de réponse sont appliqués, et la réponse résultante sera renvoyée au navigateur. Sinon, la gestion par défaut des exceptions intervient.

Encore une fois, les intergiciels sont exécutés dans l’ordre inverse lors de la phase de réponse, ce qui comprend process_exception. Si un intergiciel d’exception renvoie une réponse, les méthodes process_exception des classes d’intergiciels situées au-dessus ne seront pas du tout appelées.

process_template_response()

process_template_response(request, response)

request est un objet HttpRequest. response est l’objet TemplateResponse (ou équivalent) renvoyé par une vue Django ou par un intergiciel.

process_template_response() est appelée juste après la fin de l’exécution de la vue, pour autant que l’instance réponse possède une méthode render(), ce qui laisse penser qu’il s’agit d’un objet TemplateResponse ou d’un équivalent.

Elle doit renvoyer un objet réponse qui implémente une méthode render. Elle peut modifier la réponse donnée en changeant response.template_name et response.context_data, ou elle peut créer et renvoyer une toute nouvelle classe TemplateResponse ou un équivalent.

Il n’est pas nécessaire d’effectuer explicitement le rendu des réponses, celles-ci étant automatiquement « rendues » après que tous les intergiciels de réponse ont été appelés.

Les intergiciels sont exécutés dans l’ordre inverse lors de la phase de réponse, ce qui inclut process_template_response().

Gestion des réponses en flux

Au contraire de HttpResponse, StreamingHttpResponse ne possède pas d’attribut content. En conséquence, les intergiciels ne peuvent plus compter sur le fait que toutes les réponses possèdent un attribut content. S’ils ont besoin d’accéder au contenu, ils doivent savoir s’ils ont affaire avec une réponse de type flux (streaming) et ajuster leur comportement en fonction de cela :

if response.streaming:
    response.streaming_content = wrap_streaming_content(response.streaming_content)
else:
    response.content = alter_content(response.content)

Note

Il faut toujours partir du principe que streaming_content est trop volumineux pour être stocké en mémoire. Les intergiciels de réponse peuvent l’adapter dans un nouveau générateur, mais ils ne devraient pas le consommer. L’adaptation s’implémente typiquement de cette façon :

def wrap_streaming_content(content):
    for chunk in content:
        yield alter_content(chunk)

StreamingHttpResponse autorise à la fois les itérateurs synchrones et asynchrones. La fonction enveloppeuse doit correspondre. Vérifiez StreamingHttpResponse.is_async si votre intergiciel doit prendre en charge les deux types d’itérateur.

Changed in Django 4.2:

La prise en charge des réponses en flux avec des itérateurs asynchrones a été ajoutée.

Gestion des exceptions

Django convertit automatiquement les exceptions produites par la vue ou par l’intergiciel en une réponse HTTP appropriée avec un code de statut d’erreur. Certaine exceptions sont converties en codes de statut 4xx, alors qu’une exception inconnue est convertie en un code de statut 500.

Cette conversion a lieu avant et après chaque intergiciel (vous pouvez vous représenter cela comme la fine peau entre chaque couche de l’oignon), afin que chaque intergiciel puisse toujours compter sur l’obtention d’un certain type de réponse HTTP en retour de son appel à get_response. Les intergiciels n’ont pas besoin se se soucier d’envelopper leur appel à get_response dans un bloc try/except pour gérer une exception qui aurait pu être générée par un intergiciel suivant ou par la vue. Même si l’intergiciel suivant dans la chaîne génère une exception Http404, par exemple, votre intergiciel ne verra pas cette exception ; il obtiendra à la place un objet HttpResponse avec un code status_code 404.

Vous pouvez définir DEBUG_PROPAGATE_EXCEPTIONS à True pour omettre cette conversion et propager les exceptions au niveau supérieur.

Gestion du code asynchrone

Les intergiciels peuvent prendre en charge n’importe quelle combinaison de requêtes synchrones et asynchrones. Django adapte les requêtes pour correspondre aux exigences des intergiciels si ceux-ci ne gèrent pas les deux types de requêtes, mais avec une baisse de performance.

Par défaut, Django part du principe qu’un intergiciel n’est capable de traiter que des requêtes synchrones. Pour modifier ce présupposé, définissez les attributs suivants sur la classe ou la fonction fabriquante d’intergiciel :

  • sync_capable est une variable booléenne indiquant si l’intergiciel peut gérer des requêtes synchrones. Vaut True par défaut.
  • async_capable est une variable booléenne indiquant si l’intergiciel peut gérer des requêtes asynchrones. Vaut False par défaut.

Si un intergiciel possède à la fois sync_capable = True et async_capable = True, Django lui transmet la requête sans la modifier. Dans ce cas, l’intergiciel peut savoir si la requête qu’il reçoit est asynchrone ou pas en vérifiant si l’objet get_response qu’il reçoit est une fonction coroutine, à l’aide de asgiref.sync.iscoroutinefunction.

Le module django.utils.decorators contient les décorateurs sync_only_middleware(), async_only_middleware() et sync_and_async_middleware() qui permettent d’attribuer les drapeaux adéquats aux fonctions fabriquantes d’intergiciels.

L’objet exécutable renvoyé doit correspondre à la nature synchrone ou asynchrone de la méthode get_response. Si vous recevez un get_response asynchrone, vous devez renvoyer une fonction coroutine (async def).

Les méthodes process_view, process_template_response et process_exception, quand elles sont présentes, doivent aussi être adaptées pour les modes synchrones/asynchrones. Cependant, Django les adapte individuellement si vous ne le faites pas, mais avec une perte de performance supplémentaire.

Voici un exemple de la manière de créer une fonction d’intergiciel qui prend en charge les deux modes

from asgiref.sync import iscoroutinefunction
from django.utils.decorators import sync_and_async_middleware


@sync_and_async_middleware
def simple_middleware(get_response):
    # One-time configuration and initialization goes here.
    if iscoroutinefunction(get_response):

        async def middleware(request):
            # Do something here!
            response = await get_response(request)
            return response

    else:

        def middleware(request):
            # Do something here!
            response = get_response(request)
            return response

    return middleware

Note

Si vous déclarez un intergiciel hybride qui prend en charge à la fois les appels synchrones et asynchrones, le type d’appel que vous obtenez pourrait ne pas correspondre à la vue sous-jacente. Django optimise la pile d’appel des intergiciels pour qu’il y ait le moins de transitions synchrones/asynchrones que possible.

Ainsi, même si vous enveloppez une vue asynchrone, elle pourrait être appelée en mode synchrone s’il y a d’autres intergiciels synchrones entre son exécution et la vue.

Lorsque vous utilisez un intergiciel asynchrone basé sur une classe, vous devez vous assurer que les instances sont correctement marquées comme des fonctions coroutines

from asgiref.sync import iscoroutinefunction, markcoroutinefunction


class AsyncMiddleware:
    async_capable = True
    sync_capable = False

    def __init__(self, get_response):
        self.get_response = get_response
        if iscoroutinefunction(self.get_response):
            markcoroutinefunction(self)

    async def __call__(self, request):
        response = await self.get_response(request)
        # Some logic ...
        return response

Mise à jour d’intergiciels écrits avant Django 1.10

class django.utils.deprecation.MiddlewareMixin

Django fournit django.utils.deprecation.MiddlewareMixin pour faciliter la création de classes d’intergiciel qui sont compatibles à la fois avec MIDDLEWARE et l’ancien MIDDLEWARE_CLASSES, et qui prennent en charge les requêtes synchrones et asynchrones. Toutes les classes d’intergiciel incluses dans Django sont compatibles avec les deux réglages.

Cette classe « mixin » fournit une méthode __init__() exigeant un paramètre get_response et le stockant dans self.get_response.

La méthode __call__():

  1. Appelle self.process_request(request) (si elle est définie).
  2. Appelle self.get_response(request) pour obtenir la réponse du dernier intergiciel et de la vue.
  3. Appelle self.process_response(request, response) (si elle est définie).
  4. Renvoie la réponse.

Quand elle est utilisée avec MIDDLEWARE_CLASSES, la méthode __call__() ne sera jamais utilisée ; Django appelle directement process_request() et process_response().

Dans la plupart des cas, l’héritage de cette classe « mixin » suffit à rendre compatible un intergiciel ancien style avec le nouveau système avec suffisamment de rétro-compatibilité. La nouvelle sémantique de court-circuitage ne fera pas de mal ou sera même avantageuse pour l’intergiciel existant. Dans quelques cas, une classe d’intergiciel pourrait avoir besoin de certains changements pour s’ajuster à la nouvelle sémantique.

Voici les différences de comportement entre l’utilisation de MIDDLEWARE et de MIDDLEWARE_CLASSES:

  1. Avec MIDDLEWARE_CLASSES, chaque intergiciel verra toujours sa méthode process_response appelée, même si un intergiciel précédent a court-circuité le processus en renvoyant une réponse de sa méthode process_request. Avec MIDDLEWARE, les intergiciels se comportent plus comme un oignon : les couches que parcourt une réponse jusqu’à sa sortie sont les mêmes que la requête a vu passer dans le sens inverse. Si un intergiciel court-circuite, seul cet intergiciel et ceux qui le précèdent dans MIDDLEWARE verront passer la réponse.
  2. Avec MIDDLEWARE_CLASSES, process_exception est appliquée aux exceptions générées depuis une méthode process_request d’intergiciel. Avec MIDDLEWARE, process_exception ne s’applique qu’aux exceptions générées dans la vue (ou depuis la méthode render d’une réponse TemplateResponse). Les exceptions générées depuis un intergiciel sont converties en une réponse HTTP appropriée puis transmises à l’intergiciel suivant.
  3. Avec MIDDLEWARE_CLASSES, si une méthode process_response génère une exception, les méthodes process_response de tous les intergiciels précédents sont omises et une réponse HTTP 500 erreur de serveur interne est toujours renvoyée (même si l’exception générée était par exemple Http404). Avec MIDDLEWARE, une exception générée depuis un intergiciel est immédiatement convertie en une réponse HTTP appropriée, puis le prochain intergiciel dans la chaîne verra la réponse. Les intergiciels ne sont jamais outrepassés en raison d’une exception générée dans un autre intergiciel.
Back to Top