{"id":2239,"date":"2026-02-17T10:03:56","date_gmt":"2026-02-17T08:03:56","guid":{"rendered":"https:\/\/lightrest.codeline.fr\/?page_id=2239"},"modified":"2026-03-16T19:22:01","modified_gmt":"2026-03-16T17:22:01","slug":"les-hooks","status":"publish","type":"page","link":"https:\/\/lightws.codeline.fr\/index.php\/lightrest-composant-rest-windev\/lightrest-documentation\/les-hooks\/","title":{"rendered":"Les HOOKS"},"content":{"rendered":"\n

Les HOOKS<\/strong> (ou intercepteurs d’\u00e9v\u00e8nements<\/em>) permettent d\u2019ex\u00e9cuter du code automatiquement \u00e0 des moments cl\u00e9s du cycle de vie d\u2019une requ\u00eate LightREST.<\/p>\n\n\n\n

Ils servent \u00e0 g\u00e9rer proprement tous les traitements transverses<\/strong> (non m\u00e9tier), sans polluer le code des routes : s\u00e9curit\u00e9, logs, m\u00e9triques, tra\u00e7age, normalisation des r\u00e9ponses, gestion centralis\u00e9e des erreurs, etc.<\/p>\n\n\n\n

Un handler de Hook re\u00e7oit en param\u00e8tre une structure EventInfo<\/u> <\/a>qui contient :
– Le type de l’\u00e9v\u00e8nement intercept\u00e9
– l’objet lrRequest<\/u> <\/a>de la requ\u00eate en cours (dont il peut renseigner le membre CustomData<\/u> <\/a>\u00e0 l’attention de handlers qui seront ex\u00e9cut\u00e9s ult\u00e9rieurement)
– l’objet lrResponse<\/u> <\/a>(\u00e0 compl\u00e9ter \u00e9ventuellement)
– un \u00e9ventuel message (pour les \u00e9v\u00e9nements EVE_INFO, EVE_WARNING, EVE_ERROR et EVE_PANIC)
– le Tag de la route en cours d’ex\u00e9cution

Un handler de Hook renvoie une valeur de type EventReturn<\/a><\/u> :
– EVE_OK : le traitement de la route continue normalement
– EVE_ABORT : le traitement est interrompu. Le contenu de la r\u00e9ponse (headers+body) est envoy\u00e9 au client (avec une probable erreur HTTP)
– EVE_REPLACE : utilis\u00e9 pour un \u00e9v\u00e9nement EVE_BEFORE_HANDLER il permet de court-circuiter l’ex\u00e9cution du handler par d\u00e9faut de la route en cours<\/p>\n\n\n\n

Le projet WinDev LightRestHooksDemo (pr\u00e9sent dans la distribution \u00e0 partir de la v3.2) illustre les fondamentaux des Hooks.<\/p>\n\n\n\n

\n\n\n\n

Int\u00e9r\u00eat<\/h2>\n\n\n\n

Un hook est une fonction appel\u00e9e par LightREST \u00e0 un instant pr\u00e9cis du traitement d\u2019une requ\u00eate.<\/p>\n\n\n\n

Il permet notamment de :<\/p>\n\n\n\n

    \n
  • Ex\u00e9cuter un traitement alternatif<\/strong> qui remplacera celui de la ROUTE appel\u00e9e<\/li>\n\n\n\n
  • Filter<\/strong> \/ compl\u00e9ter<\/strong> \/ remplacer<\/strong> \/ modifier<\/strong> le contenu d’une r\u00e9ponse REST<\/li>\n\n\n\n
  • Bloquer<\/strong> l’utilisation d’une API si certains crit\u00e8res ne sont pas remplis (ex: g\u00e9ographiques), ou interdire l’ex\u00e9cution d’une ROUTE (droits)<\/li>\n\n\n\n
  • Injecter des donn\u00e9es<\/strong> dans l’objet lrRequest re\u00e7u par un handler REST (membre CustomData)<\/li>\n\n\n\n
  • Centraliser la journalisation<\/strong> (logs structur\u00e9s, dur\u00e9e, statut HTTP\u2026)<\/li>\n\n\n\n
  • Impl\u00e9menter l\u2019authentification \/ autorisation<\/strong> de mani\u00e8re uniforme<\/li>\n\n\n\n
  • Ajouter du tra\u00e7age<\/strong> (Correlation ID, audit, conformit\u00e9)<\/li>\n\n\n\n
  • Collecter des m\u00e9triques de performance<\/strong><\/li>\n\n\n\n
  • Appliquer des r\u00e8gles globales (CORS, headers de s\u00e9curit\u00e9, cache-control\u2026)<\/li>\n\n\n\n
  • Normaliser les r\u00e9ponses<\/strong> et les erreurs<\/strong><\/li>\n\n\n\n
  • \u00c9viter la duplication<\/strong> de code dans chaque route<\/li>\n<\/ul>\n\n\n\n
    \n\n\n\n

    Avantages cl\u00e9s<\/h3>\n\n\n\n
      \n
    • Coh\u00e9rence<\/strong> : m\u00eames r\u00e8gles appliqu\u00e9es partout<\/li>\n\n\n\n
    • Lisibilit\u00e9<\/strong> : les routes restent focalis\u00e9es sur le m\u00e9tier<\/li>\n\n\n\n
    • Maintenance<\/strong> : un changement transverse se fait en un seul endroit<\/li>\n\n\n\n
    • Robustesse<\/strong> : moins d\u2019oublis, moins de divergences de comportement<\/li>\n<\/ul>\n\n\n\n
      \n\n\n\n

      Cycle de vie d\u2019une requ\u00eate et position des hooks<\/h2>\n\n\n\n
      \"\"<\/figure>\n\n\n\n

      Le traitement typique d\u2019une requ\u00eate REST suit ce sch\u00e9ma :<\/p>\n\n\n\n

        \n
      1. Ouverture d’une connexion (EVE_CONNECT)<\/li>\n\n\n\n
      2. R\u00e9ception de la requ\u00eate REST (EVE_RECEIVED)<\/li>\n\n\n\n
      3. Ex\u00e9cution du hook avant handler<\/em> (EVE_BEFORE_HANDLER)<\/li>\n\n\n\n
      4. Ex\u00e9cution du handler de route<\/li>\n\n\n\n
      5. Ex\u00e9cution du hook apr\u00e8s handler<\/em> (EVE_BEFORE_HANDLER)<\/li>\n\n\n\n
      6. Ajout des \u00e9ventuels headers automatiques (niveau serveur et route)<\/li>\n\n\n\n
      7. Ex\u00e9cution du hook avant envoi de la r\u00e9ponse<\/em> (EVE_RESULT)<\/li>\n\n\n\n
      8. Envoi du r\u00e9sultat au client REST<\/li>\n<\/ol>\n\n\n\n

        En cas d\u2019erreur (erreur applicative, panic, timeout\u2026), des hooks sp\u00e9cifiques peuvent \u00eatre ex\u00e9cut\u00e9s afin de produire une r\u00e9ponse coh\u00e9rente et effectuer les nettoyages n\u00e9cessaires.<\/p>\n\n\n\n

        \n

        \u26a0\ufe0f Certains hooks peuvent \u00eatre ex\u00e9cut\u00e9s m\u00eame si le client a d\u00e9j\u00e0 coup\u00e9 la connexion (timeout d\u2019\u00e9criture, socket ferm\u00e9).<\/p>\n<\/blockquote>\n\n\n\n

        \n\n\n\n

        Principe<\/h2>\n\n\n\n
          \n
        • Un ou plusieurs hooks sont enregistr\u00e9s<\/strong> sur le serveur ou sur une route.<\/li>\n\n\n\n
        • Chaque hook est associ\u00e9 \u00e0 une phase d\u2019ex\u00e9cution<\/strong> (EVE_CONNECT, EVE_BEFORE_HANDLER, EVE_ERROR, …) .<\/li>\n\n\n\n
        • Un hook re\u00e7oit le contexte de requ\u00eate<\/strong> et peut :\n
            \n
          • Lire ou modifier la requ\u00eate et la r\u00e9ponse<\/li>\n\n\n\n
          • Ajouter des informations contextuelles<\/li>\n\n\n\n
          • Stopper le traitement<\/li>\n\n\n\n
          • D\u00e9clencher une erreur contr\u00f4l\u00e9e<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n\n\n\n

            R\u00e8gles importantes<\/h3>\n\n\n\n
              \n
            • Un hook doit \u00eatre rapide<\/strong> (\u00e9viter toute I\/O bloquante).<\/li>\n\n\n\n
            • Il doit \u00eatre s\u00fbr en concurrence<\/strong> (aucun \u00e9tat global mutable non prot\u00e9g\u00e9).<\/li>\n\n\n\n
            • Il ne doit jamais exposer de donn\u00e9es sensibles<\/strong> dans les logs.<\/li>\n\n\n\n
            • Les d\u00e9cisions globales (auth, CORS, headers communs) doivent \u00eatre trait\u00e9es ici, pas dans les routes.<\/li>\n<\/ul>\n\n\n\n
              \n\n\n\n

              Ev\u00e9nements du m\u00e9canisme de hooks<\/h2>\n\n\n\n

              Les Hooks peuvent \u00eatre d\u00e9clar\u00e9s niveau Serveur et\/ou Route selon leur type. Un m\u00eame \u00e9v\u00e9nement \u00ab\u00a0Hook\u00e9\u00a0\u00bb sur les 2 niveaux sera d’abord ex\u00e9cut\u00e9 sur l’objet Serveur et ensuite sur l’objet Route.

              Plusieurs \u00e9v\u00e9nements peuvent \u00eatre attach\u00e9s \u00e0 un m\u00eame Hook (par exemple un m\u00eame handler pourra g\u00e9rer EVE_ERROR, EVE_WARNING et EVE_PANIC).
              <\/p>\n\n\n\n

              \n

              <\/p>\n<\/blockquote>\n\n\n\n

              EVE_INFO<\/code><\/td>Hook serveur. Information sur l’ex\u00e9cution<\/strong><\/td><\/tr>
              EVE_STARTING<\/code><\/td>Hook serveur. En cours de d\u00e9marrage<\/strong><\/td><\/tr>
              EVE_STARTED<\/code><\/td>Hook serveur. D\u00e9marr\u00e9<\/strong><\/td><\/tr>
              EVE_STOPPING<\/code><\/td>Hook serveur. En cours d’arr\u00eat<\/strong><\/td><\/tr>
              EVE_STOPPED<\/code><\/td>Hook serveur. Arr\u00eat\u00e9<\/strong><\/td><\/tr>
              EVE_CONNECT<\/code><\/td>Hook serveur. Nouvelle connexion<\/strong> (permet par exemple de filtrer les connexions par adresse IP)<\/td><\/tr>
              EVE_RECEIVED<\/code><\/td>Hook serveur et route. R\u00e9ception d’une requ\u00eate REST<\/strong><\/td><\/tr>
              EVE_AUTH_FAILED<\/code><\/td>Hook serveur et route. Authentification \u00e9chou\u00e9e<\/strong><\/td><\/tr>
              EVE_BEFORE_HANDLER<\/code><\/td>Hook serveur et route. Avant ex\u00e9cution de la route<\/strong><\/td><\/tr>
              EVE_AFTER_HANDLER<\/code><\/td>Hook serveur et route. Apr\u00e8s ex\u00e9cution de la route<\/strong><\/td><\/tr>
              EVE_RESULT<\/code><\/td>Hook serveur et route. Avant envoi du r\u00e9sultat<\/strong> (\u00e9tape ultime pour v\u00e9rifier, compl\u00e9ter, chiffrer, signer, filtrer, limiter, journaliser, …) la r\u00e9ponse avant envoi au client.<\/td><\/tr>
              EVE_ERROR<\/code><\/td>Hook serveur. Erreur<\/strong> lors de l’ex\u00e9cution<\/td><\/tr>
              EVE_WARNING<\/code><\/td>Hook serveur. Warning<\/strong> lors de l’ex\u00e9cution<\/td><\/tr>
              EVE_PANIC<\/code><\/td>Hook serveur. Erreur grave<\/strong> lors de l’ex\u00e9cution<\/td><\/tr><\/tbody><\/table><\/figure>\n\n\n\n
              \n\n\n\n

              Exemple<\/p>\n\n\n\n

                \n
              • Authentification centralis\u00e9e via un hook serveur<\/li>\n\n\n\n
              • V\u00e9rification d\u2019un token dans le header Authorization<\/em><\/li>\n\n\n\n
              • Retour 401 Unauthorized<\/strong> avec une r\u00e9ponse JSON standardis\u00e9e<\/li>\n\n\n\n
              • Aucune route n\u2019a besoin de g\u00e9rer l\u2019authentification<\/li>\n<\/ul>\n\n\n\n
                \/\/ =======================================================\n\/\/ Hook \u00e9v\u00e9nementiel : gestion de l\u2019authentification \n\/\/ =======================================================\nPROC\u00c9DURE ServerEventHook(stInfo lrHook.lrEventInfo) : lrHook.lrEventReturn\n\n    SI stInfo.Request.GetHeaderValue(\"ID\")=\"\" ALORS\n\n      stInfo.Response:Status      = lrResponse::StatusUnauthorized\n      stInfo.Response:ContentType = lrResponse::ContentTXT\n      stInfo.Response:Body        = \"Token ID manquant\"\n\n      \/\/ Stoppe le pipeline : la route ne sera pas ex\u00e9cut\u00e9e\n      RENVOYER lrHook::EVE_ABORT\n   FIN\n\n   RENVOYER lrHook::EVE_OK\nFIN\n<\/code><\/pre>\n\n\n\n
                <\/p>\n","protected":false},"excerpt":{"rendered":"
                Les HOOKS (ou intercepteurs d’\u00e9v\u00e8nements) permettent d\u2019ex\u00e9cuter du code automatiquement \u00e0 des moments cl\u00e9s du cycle de vie d\u2019une requ\u00eate LightREST. Ils servent \u00e0 g\u00e9rer proprement tous les traitements transverses (non m\u00e9tier), sans polluer le code des routes : s\u00e9curit\u00e9, logs, m\u00e9triques, tra\u00e7age, normalisation des r\u00e9ponses, gestion centralis\u00e9e des erreurs, etc. Un handler de Hook re\u00e7oit en param\u00e8tre une structure […]<\/p>\n","protected":false},"author":2,"featured_media":0,"parent":161,"menu_order":1,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-2239","page","type-page","status-publish","hentry"],"aioseo_notices":[],"aioseo_head":"\n\t\t\n\t\n\t\n\t\n\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t\n\t\t