granicus.if.org Git - apache/blob - docs/manual/mod/mod_lua.html.fr

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="fr" xml:lang="fr"><head>
   4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
   5 <!--
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7               This file is generated from xml source: DO NOT EDIT
   8         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   9       -->
  10 <title>mod_lua - Serveur Apache HTTP Version 2.5</title>
  11 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  12 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  13 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  14 <script src="../style/scripts/prettify.min.js" type="text/javascript">
  15 </script>
  16
  17 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  18 <body>
  19 <div id="page-header">
  20 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p>
  21 <p class="apache">Serveur Apache HTTP Version 2.5</p>
  22 <img alt="" src="../images/feather.png" /></div>
  23 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  24 <div id="path">
  25 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">Serveur HTTP</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Modules</a></div>
  26 <div id="page-content">
  27 <div id="preamble"><h1>Module Apache mod_lua</h1>
  28 <div class="toplang">
  29 <p><span>Langues Disponibles: </span><a href="../en/mod/mod_lua.html" hreflang="en" rel="alternate" title="English">&nbsp;en&nbsp;</a> |
  30 <a href="../fr/mod/mod_lua.html" title="Français">&nbsp;fr&nbsp;</a></p>
  31 </div>
  32 <table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Fournit des points d'entrée Lua dans différentes parties du
  33 traitement des requêtes httpd</td></tr>
  34 <tr><th><a href="module-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
  35 <tr><th><a href="module-dict.html#ModuleIdentifier">Identificateur de Module:</a></th><td>lua_module</td></tr>
  36 <tr><th><a href="module-dict.html#SourceFile">Fichier Source:</a></th><td>mod_lua.c</td></tr>
  37 <tr><th><a href="module-dict.html#Compatibility">Compatibilité:</a></th><td>versions 2.3 et supérieures</td></tr></table>
  38 <h3>Sommaire</h3>
  39
  40 <p>Ce module permet d'ajouter au serveur des extensions sous forme de
  41 scripts écrits dans le langage de programmation Lua.
  42 <code class="module"><a href="../mod/mod_lua.html">mod_lua</a></code> fournit de nombreuses extensions
  43 (hooks) disponibles avec les modules natifs du serveur HTTP Apache,
  44 comme les associations de requêtes à des fichiers, la génération de
  45 réponses dynamiques, le contrôle d'accès, l'authentification et
  46 l'autorisation.</p>
  47
  48 <p>Vous trouverez davantage d'informations à propos du langage de
  49 programmation Lua sur <a href="http://www.lua.org/">le site web de
  50 Lua</a>.</p>
  51
  52 <div class="note"><code>mod_lua</code> est encore au stade expérimental. Son mode
  53 d'utilisation et son comportement pourront changer à tout moment jusqu'à
  54 ce qu'il passe au stade stable, et ce même entre deux versions stables
  55 2.4.x. N'oublez pas de consulter le fichier CHANGES avant toute mise à
  56 jour.</div>
  57
  58 <div class="warning"><h3>Avertissement</h3>
  59 <p>Ce module possède une grande capacité d'action sur le fonctrionnement
  60 de httpd, ce qui lui confère une grande puissance, mais peut aussi
  61 induire un risque de sécurité. Il est déconseillé d'utiliser ce module
  62 sur un serveur partagé avec des utilisateurs auxquels vous ne pouvez pas
  63 accorder une confiance absolue, car il peut permettre de modifier le
  64 fonctionnement interne de httpd.</p>
  65 </div>
  66
  67 </div>
  68 <div id="quickview"><h3>Sujets</h3>
  69 <ul id="topics">
  70 <li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Configuration de base</a></li>
  71 <li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Ecrire des gestionnaires</a></li>
  72 <li><img alt="" src="../images/down.gif" /> <a href="#writingauthzproviders">Ecriture de fournisseurs d'autorisation</a></li>
  73 <li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Ecriture de fonctions d'accroche
  74 (hooks)</a></li>
  75 <li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Structures de données</a></li>
  76 <li><img alt="" src="../images/down.gif" /> <a href="#functions">Méthodes de l'objet request_rec</a></li>
  77 <li><img alt="" src="../images/down.gif" /> <a href="#logging">Fonctions de journalisation</a></li>
  78 <li><img alt="" src="../images/down.gif" /> <a href="#apache2">Paquet apache2</a></li>
  79 <li><img alt="" src="../images/down.gif" /> <a href="#modifying_buckets">Modification de contenu avec les filtres lua</a></li>
  80 <li><img alt="" src="../images/down.gif" /> <a href="#databases">Connectivité aux bases de données</a></li>
  81 </ul><h3 class="directives">Directives</h3>
  82 <ul id="toc">
  83 <li><img alt="" src="../images/down.gif" /> <a href="#luaauthzprovider">LuaAuthzProvider</a></li>
  84 <li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li>
  85 <li><img alt="" src="../images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li>
  86 <li><img alt="" src="../images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li>
  87 <li><img alt="" src="../images/down.gif" /> <a href="#luahookcheckuserid">LuaHookCheckUserID</a></li>
  88 <li><img alt="" src="../images/down.gif" /> <a href="#luahookfixups">LuaHookFixups</a></li>
  89 <li><img alt="" src="../images/down.gif" /> <a href="#luahookinsertfilter">LuaHookInsertFilter</a></li>
  90 <li><img alt="" src="../images/down.gif" /> <a href="#luahooklog">LuaHookLog</a></li>
  91 <li><img alt="" src="../images/down.gif" /> <a href="#luahookmaptostorage">LuaHookMapToStorage</a></li>
  92 <li><img alt="" src="../images/down.gif" /> <a href="#luahooktranslatename">LuaHookTranslateName</a></li>
  93 <li><img alt="" src="../images/down.gif" /> <a href="#luahooktypechecker">LuaHookTypeChecker</a></li>
  94 <li><img alt="" src="../images/down.gif" /> <a href="#luainherit">LuaInherit</a></li>
  95 <li><img alt="" src="../images/down.gif" /> <a href="#luainputfilter">LuaInputFilter</a></li>
  96 <li><img alt="" src="../images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li>
  97 <li><img alt="" src="../images/down.gif" /> <a href="#luaoutputfilter">LuaOutputFilter</a></li>
  98 <li><img alt="" src="../images/down.gif" /> <a href="#luapackagecpath">LuaPackageCPath</a></li>
  99 <li><img alt="" src="../images/down.gif" /> <a href="#luapackagepath">LuaPackagePath</a></li>
 100 <li><img alt="" src="../images/down.gif" /> <a href="#luaquickhandler">LuaQuickHandler</a></li>
 101 <li><img alt="" src="../images/down.gif" /> <a href="#luaroot">LuaRoot</a></li>
 102 <li><img alt="" src="../images/down.gif" /> <a href="#luascope">LuaScope</a></li>
 103 </ul>
 104 <h3>Traitement des bugs</h3><ul class="seealso"><li><a href="https://www.apache.org/dist/httpd/CHANGES_2.4">Journal des modifications de httpd</a></li><li><a href="https://bz.apache.org/bugzilla/buglist.cgi?bug_status=__open__&amp;list_id=144532&amp;product=Apache%20httpd-2&amp;query_format=specific&amp;order=changeddate%20DESC%2Cpriority%2Cbug_severity&amp;component=mod_lua">Problèmes connus</a></li><li><a href="https://bz.apache.org/bugzilla/enter_bug.cgi?product=Apache%20httpd-2&amp;component=mod_lua">Signaler un bug</a></li></ul><h3>Voir aussi</h3>
 105 <ul class="seealso">
 106 <li><a href="#comments_section">Commentaires</a></li></ul></div>
 107 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 108 <div class="section">
 109 <h2><a name="basicconf" id="basicconf">Configuration de base</a></h2>
 110
 111 <p>La directive de base pour le chargement du module est</p>
 112
 113 <pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre>
 114
 115
 116 <p>
 117 <code>mod_lua</code> fournit un gestionnaire nommé
 118 <code>lua-script</code> qui peut être utilisé avec une directive
 119 <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code> ou <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> :</p>
 120
 121 <pre class="prettyprint lang-config">&lt;Files "*.lua"&gt;
 122     SetHandler lua-script
 123 &lt;/Files&gt;</pre>
 124
 125
 126 <p>
 127 Ceci aura pour effet de faire traiter les requêtes pour les fichiers
 128 dont l'extension est <code>.lua</code> par <code>mod_lua</code> en
 129 invoquant cette fonction de <code>gestion</code> de fichier.
 130 </p>
 131
 132 <p>Pour plus de détails, voir la directive
 133 <code class="directive">LuaMapHandler</code>.
 134  </p>
 135 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 136 <div class="section">
 137 <h2><a name="writinghandlers" id="writinghandlers">Ecrire des gestionnaires</a></h2>
 138 <p>Dans l'API du serveur HTTP Apache, un gestionnaire est une sorte de
 139 point d'accroche (hook) spécifique responsable de la génération de la
 140 réponse. <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, <code class="module"><a href="../mod/mod_cgi.html">mod_cgi</a></code> et
 141 <code class="module"><a href="../mod/mod_status.html">mod_status</a></code> sont des exemples de modules comportant un
 142 gestionnaire.</p>
 143
 144 <p><code>mod_lua</code> cherche toujours à invoquer une fonction Lua pour le
 145 gestionnaire, plutôt que de simplement évaluer le corps d'un script dans
 146 le style de CGI. Une fonction de gestionnaire se présente comme suit :</p>
 147
 148
 149 <pre class="prettyprint lang-lua">
 150 <strong>example.lua</strong><br />
 151 -- exemple de gestionnaire
 152
 153 require "string"
 154
 155 --[[
 156      Il s'agit du nom de méthode par défaut pour les gestionnaires Lua ;
 157      voir les noms de fonctions optionnels dans la directive
 158      LuaMapHandler pour choisir un point d'entrée différent.
 159 --]]
 160 function handle(r)
 161     r.content_type = "text/plain"
 162
 163     if r.method == 'GET' then
 164         r:puts("Hello Lua World!\n")
 165         for k, v in pairs( r:parseargs() ) do
 166             r:puts( string.format("%s: %s\n", k, v) )
 167         end
 168     elseif r.method == 'POST' then
 169         r:puts("Hello Lua World!\n")
 170         for k, v in pairs( r:parsebody() ) do
 171             r:puts( string.format("%s: %s\n", k, v) )
 172         end
 173     else
 174     elseif r.method == 'PUT' then
 175 -- message d'erreur personnalisé
 176         r:puts("Unsupported HTTP method " .. r.method)
 177         r.status = 405
 178         return apache2.OK
 179     else
 180 -- message d'erreur ErrorDocument
 181         return 501
 182     end
 183     return apache2.OK
 184 end</pre>
 185
 186
 187 <p>
 188 Ce gestionnaire se contente d'afficher les arguments codés d'un uri ou
 189 d'un formulaire dans un page au format texte.
 190 </p>
 191
 192 <p>
 193 Cela signifie que vous pouvez (et êtes encouragé à) avoir plusieurs
 194 gestionnaires (ou points d'entrée, ou filtres) dans le même script.
 195 </p>
 196
 197 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 198 <div class="section">
 199 <h2><a name="writingauthzproviders" id="writingauthzproviders">Ecriture de fournisseurs d'autorisation</a></h2>
 200
 201
 202 <p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> fournit une interface d'autorisation
 203 de haut niveau bien plus facile à utiliser que dans les hooks
 204 correspondants. Le premier argument de la directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> permet de spécifier le
 205 fournisseur d'autorisation à utiliser. Pour chaque directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>,
 206 <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> appellera le fournisseur d'autorisation
 207 spécifié, le reste de la ligne constituant les paramètres. Le
 208 fournisseur considéré va alors vérifier les autorisations et fournir le
 209 résultat dans une valeur de retour.</p>
 210
 211 <p>En général, le fournisseur authz est appelé avant l'authentification.
 212 S'il doit connaître le nom d'utilisateur authentifié (ou si
 213 l'utilisateur est appelé à être authentifié), le fournisseur doit
 214 renvoyer <code>apache2.AUTHZ_DENIED_NO_USER</code>, ce qui va
 215 déclancher le processus d'authentification et un deuxième appel du
 216 fournisseur authz.</p>
 217
 218 <p>La fonction du fournisseur authz ci-dessous accepte deux arguments,
 219 une adresse IP et un nom d'utilisateur. Elle autorise l'accès dans le
 220 cas où la requête provient de l'adresse IP spécifiée, ou si
 221 l'utilisateur authentifié correspond au second argument :</p>
 222
 223 <pre class="prettyprint lang-lua">
 224 <strong>authz_provider.lua</strong><br />
 225
 226 require 'apache2'
 227
 228 function authz_check_foo(r, ip, user)
 229     if r.useragent_ip == ip then
 230         return apache2.AUTHZ_GRANTED
 231     elseif r.user == nil then
 232         return apache2.AUTHZ_DENIED_NO_USER
 233     elseif r.user == user then
 234         return apache2.AUTHZ_GRANTED
 235     else
 236         return apache2.AUTHZ_DENIED
 237     end
 238 end</pre>
 239
 240
 241 <p>La configuration suivante enregistre cette fonction en tant que
 242 fournisseur <code>foo</code>, et la configure por l'URL <code>/</code> :</p>
 243 <pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo
 244 &lt;Location "/"&gt;
 245   Require foo 10.1.2.3 john_doe
 246 &lt;/Location&gt;</pre>
 247
 248
 249 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 250 <div class="section">
 251 <h2><a name="writinghooks" id="writinghooks">Ecriture de fonctions d'accroche
 252 (hooks)</a></h2>
 253
 254 <p>Les fonctions d'accroche déterminent la manière dont les modules (et
 255 les scripts Lua) participent au traitement des requêtes. Chaque type
 256 d'accroche proposé par le serveur a un rôle spécifique, comme
 257 l'association de requêtes au système de fichiers, le contrôle d'accès,
 258 ou la définition de types MIME : </p>
 259
 260 <table class="bordered"><tr class="header">
 261         <th>Phase d'accroche</th>
 262         <th>Directive mod_lua</th>
 263         <th>Description</th>
 264     </tr>
 265 <tr>
 266         <td>Gestionnaire rapide</td>
 267         <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td>
 268         <td>Il s'agit de la première accroche appelée lorsqu'une requête
 269         a été associée à un serveur ou un serveur virtuel.</td>
 270     </tr>
 271 <tr class="odd">
 272         <td>Phase de traduction</td>
 273         <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td>
 274         <td>Cette phase traduit l'URI de la requête en nom de fichier
 275         sur le système. Ce sont des modules comme
 276         <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> et <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> qui
 277         interviennent au cours de cette phase.</td>
 278     </tr>
 279 <tr>
 280         <td>Choix du lieu de stockage de la ressource</td>
 281         <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td>
 282         <td>Cette phase définit le lieu de stockage de la ressource :
 283         physique, en cache ou externe/mandaté. Elle est assurée par les
 284         modules de mandat ou de mise en cache.</td>
 285     </tr>
 286 <tr class="odd">
 287         <td>Autorisation d'accès</td>
 288         <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td>
 289         <td>Cette phase vérifie si un client a l'autorisation d'accès à
 290         la ressource. Elle s'exécute avant l'authentification de
 291         l'utisateur ; il faut donc être prudent.
 292         </td>
 293     </tr>
 294 <tr>
 295         <td>Vérification de l'identifiant utilisateur</td>
 296         <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td>
 297         <td>Cette phase vérifie l'identifiant de l'utilisateur ayant
 298         fait l'objet d'une négociation.</td>
 299     </tr>
 300 <tr class="odd">
 301         <td>Vérification de l'autorisation d'accès</td>
 302         <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code>
 303         ou
 304             <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td>
 305         <td>Cette phase vérifie l'autorisation d'accès d'un utilisateur
 306         en fonction des ses paramètres de connexion, comme
 307         l'identifiant, le certificat, etc...
 308         </td>
 309     </tr>
 310 <tr>
 311         <td>Vérification du type de la ressource</td>
 312         <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td>
 313         <td>Cette phase assigne un type de contenu et un gestionnaire à
 314         la ressource.</td>
 315     </tr>
 316 <tr class="odd">
 317         <td>Derniers réglages</td>
 318         <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td>
 319         <td>C'est la dernière phase avant l'activation des gestionnaires
 320         de contenu. Toute modification de dernière minute à la requête
 321         doit être effectuée ici.</td>
 322     </tr>
 323 <tr>
 324         <td>Gestionnaire de contenu</td>
 325         <td>fichiers fx. <code>.lua</code> ou directive <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td>
 326         <td>C'est durant cette phase que le contenu est traité. Les
 327         fichiers sont lus, interprétés, certains sont exécutés, et le
 328         résultat obtenu est envoyé au client.</td>
 329     </tr>
 330 <tr class="odd">
 331         <td>Journalisation</td>
 332         <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
 333         <td>Lorsqu'une requête a été traitée, plusieurs phases de
 334         journalisation interviennent, et enregistrent leurs résultats
 335         dans les fichiers d'erreur ou d'accès. Mod_lua peut
 336         s'intercaler au départ de ce processus et ainsi contrôler la
 337         journalisation.</td>
 338     </tr>
 339 </table>
 340
 341 <p>Les fonctions d'accroche reçoivent l'objet de la requête comme seul
 342 argument (sauf LuaAuthzProvider qui reçoit aussi des arguments en
 343 provenance de la directive Require). Elles peuvent renvoyer une valeur,
 344 selon la fonction, mais il s'agit en général d'un
 345 code d'état HTTP ou des valeurs OK, DONE, ou DECLINED,
 346 que vous pouvez écrire dans Lua sous la forme <code>apache2.OK</code>,
 347 <code>apache2.DONE</code>, ou <code>apache2.DECLINED</code>.</p>
 348
 349
 350 <pre class="prettyprint lang-lua">
 351 <strong>translate_name.lua</strong><br />
 352 -- exemple d'accroche qui réécrit un URI en chemin du système de fichiers.
 353
 354 require 'apache2'
 355
 356 function translate_name(r)
 357     if r.uri == "/translate-name" then
 358         r.filename = r.document_root .. "/find_me.txt"
 359         return apache2.OK
 360     end
 361     -- on ne gère pas cette URL et on donne sa chance à un autre module
 362     return apache2.DECLINED
 363 end</pre>
 364
 365
 366
 367 <pre class="prettyprint lang-lua">
 368 <strong>translate_name2.lua</strong><br />
 369 --[[ exemple d'accroche qui réécrit un URI vers un autre URI. Il renvoie
 370         un apache2.DECLINED pour permettre à un autre interpréteur d'URL de
 371         travailler sur la substitution, y compris l'accroche translate_name
 372         de base dont les tables de correspondances se basent sur DocumentRoot.
 373
 374      Note: utilisez le drapeau early/late de la directive pour
 375      l'exécuter avant ou après mod_alias.
 376 --]]
 377
 378 require 'apache2'
 379
 380 function translate_name(r)
 381     if r.uri == "/translate-name" then
 382         r.uri = "/find_me.txt"
 383         return apache2.DECLINED
 384     end
 385     return apache2.DECLINED
 386 end</pre>
 387
 388 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 389 <div class="section">
 390 <h2><a name="datastructures" id="datastructures">Structures de données</a></h2>
 391
 392 <dl>
 393 <dt>request_rec</dt>
 394         <dd>
 395         <p>request_rec est considérée en tant que donnée utilisateur.
 396         Elle possède une métatable qui vous permet d'accomplir des
 397         choses intéressantes. Pour la plus grande partie, elle possède
 398         les mêmes champs que la structure request_rec, la
 399         plupart d'entre eux étant accessibles en lecture et écriture (le
 400         contenu des champs de la table peut être modifié, mais les
 401         champs eux-mêmes ne peuvent pas être établis en tant que tables
 402         distinctes).</p>
 403
 404         <table class="bordered"><tr class="header">
 405           <th><strong>Nom</strong></th>
 406           <th><strong>Type Lua</strong></th>
 407           <th><strong>Modifiable</strong></th>
 408           <th><strong>Description</strong></th>
 409         </tr>
 410 <tr>
 411           <td><code>allowoverrides</code></td>
 412           <td>string</td>
 413           <td>non</td>
 414           <td>L'option AllowOverride s'applique à la requête courante.</td>
 415         </tr>
 416 <tr class="odd">
 417           <td><code>ap_auth_type</code></td>
 418           <td>string</td>
 419           <td>non</td>
 420           <td>Ce champ contient le type d'authentification effectuée
 421           (par exemple <code>basic</code>)</td>
 422         </tr>
 423 <tr>
 424           <td><code>args</code></td>
 425           <td>string</td>
 426           <td>oui</td>
 427           <td>La chaîne de paramètres de la requête (par exemple
 428           <code>foo=bar&amp;name=johnsmith</code>)</td>
 429         </tr>
 430 <tr class="odd">
 431           <td><code>assbackwards</code></td>
 432           <td>boolean</td>
 433           <td>non</td>
 434           <td>contient true s'il s'agit d'une requête de style HTTP/0.9
 435           (par exemple <code>GET /foo</code> (sans champs d'en-tête) )</td>
 436         </tr>
 437 <tr>
 438           <td><code>auth_name</code></td>
 439           <td>string</td>
 440           <td>non</td>
 441           <td>La chaîne d'identification utilisée pour la vérification
 442           de l'autorisation d'accès (si elle est disponible).</td>
 443         </tr>
 444 <tr class="odd">
 445           <td><code>banner</code></td>
 446           <td>string</td>
 447           <td>non</td>
 448           <td>La bannière du serveur, par exemple <code>Apache HTTP
 449           Server/2.4.3 openssl/0.9.8c</code></td>
 450         </tr>
 451 <tr>
 452           <td><code>basic_auth_pw</code></td>
 453           <td>string</td>
 454           <td>non</td>
 455           <td>Le mot de passe pour l'authentification de base envoyé
 456           avec la requête, s'il existe</td>
 457         </tr>
 458 <tr class="odd">
 459           <td><code>canonical_filename</code></td>
 460           <td>string</td>
 461           <td>non</td>
 462           <td>Le nom de fichier canonique de la requête</td>
 463         </tr>
 464 <tr>
 465           <td><code>content_encoding</code></td>
 466           <td>string</td>
 467           <td>non</td>
 468           <td>Le type de codage du contenu de la requête courante</td>
 469         </tr>
 470 <tr class="odd">
 471           <td><code>content_type</code></td>
 472           <td>string</td>
 473           <td>oui</td>
 474           <td>Le type de contenu de la requête courante, tel qu'il a été
 475           déterminé au cours de la phase type_check (par exemple
 476           <code>image/gif</code> ou <code>text/html</code>)</td>
 477         </tr>
 478 <tr>
 479           <td><code>context_prefix</code></td>
 480           <td>string</td>
 481           <td>non</td>
 482           <td />
 483         </tr>
 484 <tr class="odd">
 485           <td><code>context_document_root</code></td>
 486           <td>string</td>
 487           <td>non</td>
 488           <td />
 489         </tr>
 490 <tr>
 491           <td><code>document_root</code></td>
 492           <td>string</td>
 493           <td>non</td>
 494           <td>La racine des documents du serveur</td>
 495         </tr>
 496 <tr class="odd">
 497           <td><code>err_headers_out</code></td>
 498           <td>table</td>
 499           <td>non</td>
 500           <td>L'en-tête MIME de l'environnement pour la réponse, écrit
 501           même en cas d'erreur et conservé pendant les redirections
 502           internes</td>
 503         </tr>
 504 <tr>
 505           <td><code>filename</code></td>
 506           <td>string</td>
 507           <td>oui</td>
 508           <td>Le nom de fichier correspondant à la requête, par exemple
 509           /www/example.com/foo.txt. Il peut être modifié au cours des
 510           phases translate-name ou map-to-storage du traitement de la
 511           requête pour permettre au gestionnaire par défaut (ou aux
 512           gestionnaires de script) de servir une version du fichier
 513           autre que celle demandée.</td>
 514         </tr>
 515 <tr class="odd">
 516           <td><code>handler</code></td>
 517           <td>string</td>
 518           <td>oui</td>
 519           <td>Le nom du <a href="../handler.html">gestionnaire</a> qui
 520           doit traiter la requête, par exemple <code>lua-script</code>
 521           si elle doit être traitée par mod_lua. Cette valeur est en
 522           général définie via les directives <code class="directive"><a href="../mod/mod_mime.html#addhandler">AddHandler</a></code> ou <code class="directive"><a href="../mod/core.html#sethandler">SetHandler</a></code>, mais peut aussi l'être
 523           via mod_lua pour permettre à un autre gestionnaire de traiter
 524           une requête spécifique qui ne serait pas traitée par défaut
 525           par ce dernier.
 526             </td>
 527         </tr>
 528 <tr>
 529           <td><code>headers_in</code></td>
 530           <td>table</td>
 531           <td>oui</td>
 532           <td>Les en-têtes MIME de l'environnement de la requête. Il
 533           s'agit des en-têtes comme <code>Host, User-Agent,
 534           Referer</code>, etc...</td>
 535         </tr>
 536 <tr class="odd">
 537           <td><code>headers_out</code></td>
 538           <td>table</td>
 539           <td>oui</td>
 540           <td>Les en-têtes MIME de l'environnement de la réponse.</td>
 541         </tr>
 542 <tr>
 543           <td><code>hostname</code></td>
 544           <td>string</td>
 545           <td>non</td>
 546           <td>Le nom d'hôte, tel que défini par l'en-tête
 547           <code>Host:</code> ou par un URI complet.</td>
 548         </tr>
 549 <tr class="odd">
 550           <td><code>is_https</code></td>
 551           <td>boolean</td>
 552           <td>non</td>
 553           <td>Indique si la requête à été faite via HTTPS</td>
 554         </tr>
 555 <tr>
 556           <td><code>is_initial_req</code></td>
 557           <td>boolean</td>
 558           <td>non</td>
 559           <td>Indique si la requête courante est la requête initiale ou
 560           une sous-requête.</td>
 561         </tr>
 562 <tr class="odd">
 563           <td><code>limit_req_body</code></td>
 564           <td>number</td>
 565           <td>non</td>
 566           <td>La taille maximale du corps de la requête, ou 0 si aucune
 567           limite.</td>
 568         </tr>
 569 <tr>
 570         <td><code>log_id</code></td>
 571           <td>string</td>
 572           <td>non</td>
 573           <td>L'identifiant de la requête dans les journaux d'accès ou
 574           d'erreur.</td>
 575         </tr>
 576 <tr class="odd">
 577           <td><code>method</code></td>
 578           <td>string</td>
 579           <td>non</td>
 580           <td>La méthode de la requête, par exemple <code>GET</code> ou
 581           <code>POST</code>.</td>
 582         </tr>
 583 <tr>
 584           <td><code>notes</code></td>
 585           <td>table</td>
 586           <td>oui</td>
 587           <td>Une liste de notes qui peuvent être transmises d'un module
 588           à l'autre.</td>
 589         </tr>
 590 <tr class="odd">
 591           <td><code>options</code></td>
 592           <td>string</td>
 593           <td>non</td>
 594           <td>La valeur de la directive Options pour la requête
 595           courante.</td>
 596         </tr>
 597 <tr>
 598           <td><code>path_info</code></td>
 599           <td>string</td>
 600           <td>non</td>
 601           <td>La valeur de PATH_INFO extraite de la requête.</td>
 602         </tr>
 603 <tr class="odd">
 604           <td><code>port</code></td>
 605           <td>number</td>
 606           <td>non</td>
 607           <td>Le port du serveur utilisé par la requête.</td>
 608         </tr>
 609 <tr>
 610           <td><code>protocol</code></td>
 611           <td>string</td>
 612           <td>non</td>
 613           <td>Le protocole utilisé, par exemple <code>HTTP/1.1</code></td>
 614         </tr>
 615 <tr class="odd">
 616           <td><code>proxyreq</code></td>
 617           <td>string</td>
 618           <td>oui</td>
 619           <td>Indique s'il s'agit d'une requête mandatée ou non. Cette
 620           valeur est en général définie au cours de la phase
 621           post_read_request/translate_name du traitement de la requête.</td>
 622         </tr>
 623 <tr>
 624           <td><code>range</code></td>
 625           <td>string</td>
 626           <td>non</td>
 627           <td>Le contenu de l'en-tête <code>Range:</code>.</td>
 628         </tr>
 629 <tr class="odd">
 630           <td><code>remaining</code></td>
 631           <td>number</td>
 632           <td>non</td>
 633           <td>Le nombre d'octets du corps de la requête restant à lire.</td>
 634         </tr>
 635 <tr>
 636           <td><code>server_built</code></td>
 637           <td>string</td>
 638           <td>non</td>
 639           <td>La date de compilation du serveur.</td>
 640         </tr>
 641 <tr class="odd">
 642           <td><code>server_name</code></td>
 643           <td>string</td>
 644           <td>non</td>
 645           <td>Le nom du serveur pour cette requête.</td>
 646         </tr>
 647 <tr>
 648           <td><code>some_auth_required</code></td>
 649           <td>boolean</td>
 650           <td>non</td>
 651           <td>Indique si une autorisation est/était requise pour cette
 652           requête.</td>
 653         </tr>
 654 <tr class="odd">
 655           <td><code>subprocess_env</code></td>
 656           <td>table</td>
 657           <td>oui</td>
 658           <td>Le jeu de variables d'environnement pour cette requête.</td>
 659         </tr>
 660 <tr>
 661           <td><code>started</code></td>
 662           <td>number</td>
 663           <td>non</td>
 664           <td>Le moment où le serveur a été (re)démarré, en secondes
 665           depuis epoch (1er janvier 1970)</td>
 666         </tr>
 667 <tr class="odd">
 668           <td><code>status</code></td>
 669           <td>number</td>
 670           <td>oui</td>
 671           <td>Le code de retour (courant) pour cette requête, par
 672           exemple <code>200</code> ou <code>404</code>.</td>
 673         </tr>
 674 <tr>
 675           <td><code>the_request</code></td>
 676           <td>string</td>
 677           <td>non</td>
 678           <td>La chaîne de la requête telle qu'elle a été envoyée par le
 679           client, par exemple <code>GET /foo/bar HTTP/1.1</code>.</td>
 680         </tr>
 681 <tr class="odd">
 682           <td><code>unparsed_uri</code></td>
 683           <td>string</td>
 684           <td>non</td>
 685           <td>La partie URI non interprétée de la requête</td>
 686         </tr>
 687 <tr>
 688           <td><code>uri</code></td>
 689           <td>string</td>
 690           <td>oui</td>
 691           <td>L'URI après interprétation par httpd</td>
 692         </tr>
 693 <tr class="odd">
 694           <td><code>user</code></td>
 695           <td>string</td>
 696           <td>oui</td>
 697           <td>Si une authentification a été effectuée, nom de
 698           l'utilisateur authentifié.</td>
 699         </tr>
 700 <tr>
 701           <td><code>useragent_ip</code></td>
 702           <td>string</td>
 703           <td>non</td>
 704           <td>L'adresse IP de l'agent qui a envoyé la requête</td>
 705         </tr>
 706 </table>
 707         </dd>
 708     </dl>
 709 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 710 <div class="section">
 711 <h2><a name="functions" id="functions">Méthodes de l'objet request_rec</a></h2>
 712
 713 <p>L'objet request_rec possède (au minimum) les méthodes suivantes :</p>
 714
 715 <pre class="prettyprint lang-lua">r:flush()   -- vide le tampon de sortie
 716             -- Renvoie true si le vidage a été effectué avec succès,
 717             -- false dans le cas contraire.
 718
 719 while nous_avons_des_données_à_envoyer do
 720     r:puts("Bla bla bla\n") -- envoi des données à envoyer vers le tampon
 721     r:flush() -- vidage du tampon (envoi au client)
 722     r.usleep(500000) -- mise en attente pendant 0.5 secondes et bouclage
 723 end</pre>
 724
 725
 726 <pre class="prettyprint lang-lua">r:addoutputfilter(name|function) -- ajoute un filtre en sortie
 727
 728 r:addoutputfilter("fooFilter") -- insère le filtre fooFilter dans le flux de sortie</pre>
 729
 730
 731 <pre class="prettyprint lang-lua">r:sendfile(filename) -- envoie un fichier entier au client en utilisant sendfile s'il est
 732                      -- supporté par la plateforme :
 733
 734 if use_sendfile_thing then
 735     r:sendfile("/var/www/large_file.img")
 736 end</pre>
 737
 738
 739 <pre class="prettyprint lang-lua">r:parseargs() -- renvoie deux tables : une table standard de couples
 740               -- clé/valeur pour les données GET simples,
 741               -- et une autre pour les données
 742               -- multivaluées (par exemple foo=1&amp;foo=2&amp;foo=3) :
 743
 744 local GET, GETMULTI = r:parseargs()
 745 r:puts("Votre nom est : " .. GET['name'] or "Unknown")</pre>
 746
 747
 748
 749 <pre class="prettyprint lang-lua">r:parsebody()([sizeLimit]) -- interprète le corps de la
 750                            -- requête en tant que POST et renvoie
 751                            -- deux tables lua, comme r:parseargs(). Un
 752                            -- nombre optionnel peut être fourni
 753                            -- pour spécifier le nombre maximal
 754                            -- d'octets à interpréter. La
 755                            -- valeur par défaut est 8192.
 756
 757 local POST, POSTMULTI = r:parsebody(1024*1024)
 758 r:puts("Votre nom est : " .. POST['name'] or "Unknown")</pre>
 759
 760
 761
 762 <pre class="prettyprint lang-lua">r:puts("bonjour", " le monde", "!") -- affichage dans le corps de la réponse</pre>
 763
 764
 765 <pre class="prettyprint lang-lua">r:write("une simple chaîne") -- affichage dans le corps de la réponse</pre>
 766
 767
 768 <pre class="prettyprint lang-lua">r:escape_html("&lt;html&gt;test&lt;/html&gt;") -- Echappe le code HTML et renvoie le résultat</pre>
 769
 770
 771 <pre class="prettyprint lang-lua">r:base64_encode(string) -- Encode une chaîne à l'aide du standard de codage Base64.
 772
 773 local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre>
 774
 775
 776 <pre class="prettyprint lang-lua">r:base64_decode(string) -- Décode une chaîne codée en Base64.
 777
 778 local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre>
 779
 780
 781 <pre class="prettyprint lang-lua">r:md5(string) -- Calcule et renvoie le condensé MD5 d'une chaîne en mode binaire (binary safe).
 782
 783 local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre>
 784
 785
 786 <pre class="prettyprint lang-lua">r:sha1(string) -- Calcule et renvoie le condensé SHA1 d'une chaîne en mode binaire (binary safe).
 787
 788 local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre>
 789
 790
 791 <pre class="prettyprint lang-lua">r:escape(string) -- Echappe une chaîne de type URL.
 792
 793 local url = "http://foo.bar/1 2 3 &amp; 4 + 5"
 794 local escaped = r:escape(url) -- renvoie 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre>
 795
 796
 797 <pre class="prettyprint lang-lua">r:unescape(string) -- Déséchappe une chaîne de type URL.
 798
 799 local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
 800 local unescaped = r:unescape(url) -- renvoie 'http://foo.bar/1 2 3 &amp; 4 + 5'</pre>
 801
 802
 803 <pre class="prettyprint lang-lua">r:construct_url(string) -- Construit une URL à partir d'un URI
 804
 805 local url = r:construct_url(r.uri)</pre>
 806
 807
 808 <pre class="prettyprint lang-lua">r.mpm_query(number) -- Interroge le serveur à propos de son module MPM via la requête ap_mpm_query.
 809
 810 local mpm = r.mpm_query(14)
 811 if mpm == 1 then
 812     r:puts("Ce serveur utilise le MPM Event")
 813 end</pre>
 814
 815
 816 <pre class="prettyprint lang-lua">r:expr(string) -- Evalue une chaîne de type <a href="../expr.html">expr</a>.
 817
 818 if r:expr("%{HTTP_HOST} =~ /^www/") then
 819     r:puts("Ce nom d'hôte commence par www")
 820 end</pre>
 821
 822
 823 <pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Interroge le serveur à propos du
 824                         -- processus à la position <code>a</code>.
 825
 826 local process = r:scoreboard_process(1)
 827 r:puts("Le serveur 1 a comme PID " .. process.pid)</pre>
 828
 829
 830 <pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Interroge le serveur à propos du
 831                           -- thread <code>b</code>, dans le processus <code>a</code>.
 832
 833 local thread = r:scoreboard_worker(1, 1)
 834 r:puts("L'ID du thread 1 du serveur 1 est " .. thread.tid .. " et son
 835 état est " .. thread.status)</pre>
 836
 837
 838 <pre class="prettyprint lang-lua">r:clock() -- Renvoie l'heure courante avec une précision d'une microseconde.</pre>
 839
 840
 841 <pre class="prettyprint lang-lua">r:requestbody(filename) -- Lit et renvoie le corps d'une requête.
 842                         -- Si 'filename' est spécifié, le
 843                         -- corps de requête n'est pas
 844                         -- renvoyé, mais sauvegardé dans
 845                         -- le fichier correspondant.
 846
 847 local input = r:requestbody()
 848 r:puts("Vous m'avez envoyé le corps de requête suivant :\n")
 849 r:puts(input)</pre>
 850
 851
 852 <pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Ajoute le filtre en entrée 'filter_name'.</pre>
 853
 854
 855 <pre class="prettyprint lang-lua">r:module_info(module_name) -- Interroge le serveur à propos d'un module.
 856
 857 local mod = r.module_info("mod_lua.c")
 858 if mod then
 859     for k, v in pairs(mod.commands) do
 860        r:puts( ("%s: %s\n"):format(k,v)) -- affiche toutes les directives
 861                                          -- implémentées par ce module.
 862     end
 863 end</pre>
 864
 865
 866 <pre class="prettyprint lang-lua">r:loaded_modules() -- Renvoie une liste des modules chargés par httpd.
 867
 868 for k, module in pairs(r:loaded_modules()) do
 869     r:puts("J'ai chargé le module " .. module .. "\n")
 870 end</pre>
 871
 872
 873 <pre class="prettyprint lang-lua">r:runtime_dir_relative(filename) -- Génère le nom d'un fichier run-time
 874                                  -- (par exemple la mémoire partagée
 875                                  -- "file") relativement au répertoire de run-time.</pre>
 876
 877
 878 <pre class="prettyprint lang-lua">r:server_info() -- Renvoie une table contenant des informations à
 879                 -- propos du serveur, comme le nom de
 880                 -- l'exécutable httpd, le module mpm utilisé, etc...</pre>
 881
 882
 883 <pre class="prettyprint lang-lua">r:set_document_root(file_path) -- Définit la racine des documents
 884                                -- pour la requête à file_path.</pre>
 885
 886
 887 <pre class="prettyprint lang-lua">r:add_version_component(component_string) -- Ajoute un élément à
 888                                           -- la bannière du serveur.</pre>
 889
 890
 891 <pre class="prettyprint lang-lua">r:set_context_info(prefix, docroot) -- Définit le préfixe et la
 892                                     -- racine des documents du contexte pour une requête.</pre>
 893
 894
 895 <pre class="prettyprint lang-lua">r:os_escape_path(file_path) -- Convertit un chemin du système de
 896                             -- fichiers en URL indépendamment du système d'exploitation.</pre>
 897
 898
 899 <pre class="prettyprint lang-lua">r:escape_logitem(string) -- Echappe une chaîne pour journalisation.</pre>
 900
 901
 902 <pre class="prettyprint lang-lua">r.strcmp_match(string, pattern) -- Vérifie si 'string' correspond à
 903                                 -- 'pattern' via la fonction strcmp_match (GLOBs). Par exemple, est-ce que
 904                                 -- 'www.example.com' correspond à '*.example.com' ?
 905
 906 local match = r.strcmp_match("foobar.com", "foo*.com")
 907 if match then
 908     r:puts("foobar.com matches foo*.com")
 909 end</pre>
 910
 911
 912 <pre class="prettyprint lang-lua">r:set_keepalive() -- Définit l'état de persistance d'une requête.
 913                   -- Renvoie true dans la mesure du possible, false dans le cas contraire.</pre>
 914
 915
 916 <pre class="prettyprint lang-lua">r:make_etag() -- Génère et renvoie le etag pour la requête courante.</pre>
 917
 918
 919 <pre class="prettyprint lang-lua">r:send_interim_response(clear) -- Renvoie une réponse d'intérim (1xx) au
 920                                -- client. Si 'clear' est vrai, les en-têtes disponibles
 921                                -- seront envoyés et effacés.</pre>
 922
 923
 924 <pre class="prettyprint lang-lua">r:custom_response(status_code, string) -- Génère et définit une réponse
 925                                        -- personnalisée pour un code d'état particulier.
 926                                        -- Le fonctionnement est très proche de celui de la directive ErrorDocument.
 927
 928 r:custom_response(404, "Baleted!")</pre>
 929
 930
 931 <pre class="prettyprint lang-lua">r.exists_config_define(string) -- Vérifie si une définition de configuration existe.
 932
 933 if r.exists_config_define("FOO") then
 934     r:puts("httpd a probablement été lancé avec l'option -DFOO, ou FOO a
 935     été défini dans la configuration")
 936 end</pre>
 937
 938
 939 <pre class="prettyprint lang-lua">r:state_query(string) -- Interroge le serveur à propos de son état.</pre>
 940
 941
 942 <pre class="prettyprint lang-lua">r:stat(filename [,wanted]) -- Exécute stat() sur un fichier, et renvoie une table contenant
 943                            -- des informations à propos de ce fichier.
 944
 945 local info = r:stat("/var/www/foo.txt")
 946 if info then
 947     r:puts("Ce fichier existe et a été modifié pour la dernière fois à : " .. info.modified)
 948 end</pre>
 949
 950
 951 <pre class="prettyprint lang-lua">r:regex(string, pattern [,flags]) -- Exécute une recherche à base d'expression rationnelle
 952                                   -- sur une chaîne, et renvoie les éventuelles correspondances trouvées.
 953
 954 local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
 955 if matches then
 956     r:puts("L'expression rationnelle correspond et le dernier mot
 957     capturé ($2) est : " .. matches[2])
 958 end
 959
 960 -- Exemple avec insensibilité à la casse :
 961 local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)
 962
 963 -- les drapeaux peuvent être une combibaison bit à bit de :
 964 -- 0x01: insensibilité à la casse
 965 -- 0x02: recherche multiligne</pre>
 966
 967
 968 <pre class="prettyprint lang-lua">r.usleep(microsecondes) -- Interrompt l'exécution du script pendant le nombre de microsecondes spécifié.</pre>
 969
 970
 971 <pre class="prettyprint lang-lua">r:dbacquire(dbType[, dbParams]) -- Acquiert une connexion à une base de données et renvoie une classe database.
 972                                 -- Voir '<a href="#databases">Connectivité aux bases de données</a>'
 973                                 -- pour plus de détails.</pre>
 974
 975
 976 <pre class="prettyprint lang-lua">r:ivm_set("key", value) -- Défini une variable Inter-VM avec une valeur spécifique.
 977                         -- Ces valeurs sont conservées même si la VM est
 978                         -- arrêtée ou non utilisée, et ne doivent donc être
 979                         -- utilisées que si MaxConnectionsPerChild &gt; 0.
 980                         -- Les valeurs peuvent être de type number, string
 981                         -- ou boolean et sont stockées séparément pour
 982                         -- chaque processus (elles ne seront donc pas d'une
 983                         -- grande utilité si l'on utilise le mpm prefork).
 984
 985 r:ivm_get("key")        -- Lit le contenu d'une variable définie via ivm_set. Renvoie
 986                         -- le contenu de la variable si elle existe, ou nil
 987                         -- dans le cas contraire.
 988
 989 -- Voici un exemple de lecture/écriture qui sauvegarde une variable
 990 -- globale en dehors de la VM :
 991 function handle(r)
 992     -- La première VM qui effectue l'appel suivant n'obtiendra aucune
 993     -- valeur, et devra la créer
 994     local foo = r:ivm_get("cached_data")
 995     if not foo then
 996         foo = do_some_calcs() -- simulation de valeurs de retour
 997         r:ivm_set("cached_data", foo) -- définition globale de la variable
 998     end
 999     r:puts("La donnée en cache est : ", foo)
1000 end</pre>
1001
1002 <pre class="prettyprint lang-lua">r:htpassword(string [,algorithm [,cost]]) -- Génère un hash de mot de passe à partir d'une chaîne.
1003                                           -- algorithm: 0 = APMD5 (défaut), 1 = SHA, 2 = BCRYPT, 3 = CRYPT.
1004                                           -- cost: ne s'utilise qu'avec l'algorythme BCRYPT (défaut = 5).</pre>
1005
1006
1007 <pre class="prettyprint lang-lua">r:mkdir(dir [,mode]) -- Crée un répertoire et définit son mode via le paramètre optionnel mode.</pre>
1008
1009
1010 <pre class="prettyprint lang-lua">r:mkrdir(dir [,mode]) -- Crée des répertoires de manière récursive et définit
1011                       -- leur mode via le paramètre optionnel mode.</pre>
1012
1013
1014 <pre class="prettyprint lang-lua">r:rmdir(dir) -- Supprime un répertoire.</pre>
1015
1016
1017 <pre class="prettyprint lang-lua">r:touch(file [,mtime]) -- Définit la date de modification d'un fichier à la date courante ou à
1018                        -- la valeur optionnelle mtime en msec.</pre>
1019
1020
1021 <pre class="prettyprint lang-lua">r:get_direntries(dir) -- Renvoie une table contenant toutes les entrées de répertoires.
1022
1023 -- Renvoie un chemin sous forme éclatée en chemin, fichier, extension
1024 function handle(r)
1025   local dir = r.context_document_root
1026   for _, f in ipairs(r:get_direntries(dir)) do
1027     local info = r:stat(dir .. "/" .. f)
1028     if info then
1029       local mtime = os.date(fmt, info.mtime / 1000000)
1030       local ftype = (info.filetype == 2) and "[dir] " or "[file]"
1031       r:puts( ("%s %s %10i %s\n"):format(ftype, mtime, info.size, f) )
1032     end
1033   end
1034 end</pre>
1035
1036
1037 <pre class="prettyprint lang-lua">r.date_parse_rfc(string) -- Interprète une chaîne date/heure et renvoie l'équivalent en secondes depuis epoche.</pre>
1038
1039
1040 <pre class="prettyprint lang-lua">r:getcookie(key) -- Obtient un cookie HTTP</pre>
1041
1042
1043 <pre class="prettyprint lang-lua">r:setcookie(key, value, secure, expires) -- Définit un cookie HTTP, par exemple :
1044 r:setcookie("foo", "bar and stuff", false, os.time() + 86400)</pre>
1045
1046
1047 <pre class="prettyprint lang-lua">r:wsupgrade() -- Met à jour une connexion vers les WebSockets si possible (et si demandé) :
1048 if r:wsupgrade() then -- si la mise à jour est possible :
1049     r:wswrite("Bienvenue dans les websockets!") -- écrit quelque chose à l'intention du client
1050     r:wsclose()  -- Au revoir !
1051 end</pre>
1052
1053
1054 <pre class="prettyprint lang-lua">r:wsread() -- Lit un cadre de websocket depuis une connexion vers websocket mise à jour (voir ci-dessus) :
1055
1056 local line, isFinal = r:wsread() -- isFinal indique s'il s'agit du cadre final.
1057                                  -- dans le cas contraire, on peut lire les cadres suivants
1058 r:wswrite("Vous avez écrit : " .. line)</pre>
1059
1060
1061 <pre class="prettyprint lang-lua">r:wswrite(line) -- écrit un cadre vers un client WebSocket :
1062 r:wswrite("Bonjour le Monde !")</pre>
1063
1064
1065 <pre class="prettyprint lang-lua">r:wsclose() -- ferme une requête WebSocket et l'achève pour httpd :
1066
1067 if r:wsupgrade() then
1068     r:wswrite("Ecrire quelque chose : ")
1069     local line = r:wsread() or "nothing"
1070     r:wswrite("Vous avez écrit : " .. line);
1071     r:wswrite("Au revoir !")
1072     r:wsclose()
1073 end</pre>
1074
1075 <pre class="prettyprint lang-lua">r:wspeek() -- Vérifie s'il y a des données à lire
1076
1077 -- Se met en sommeil tant que rien ne nous est envoyé ...
1078 while r:wspeek() == false do
1079    r.usleep(50000)
1080 end
1081 -- Il y a des données à lire !
1082 local line = r:wsread()</pre>
1083
1084
1085
1086 <pre class="prettyprint lang-lua">r:config() -- Extrait une arborescence de l'ensemble de
1087            -- la configuration de httpd pouvant être parcourue</pre>
1088
1089
1090 <pre class="prettyprint lang-lua">r:activeconfig() -- Extrait une arborescence de la configuration active
1091                  -- de httpd (pour le serveur virtuel sélectionné)</pre>
1092
1093
1094
1095 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1096 <div class="section">
1097 <h2><a name="logging" id="logging">Fonctions de journalisation</a></h2>
1098
1099 <pre class="prettyprint lang-lua">      -- exemples de messages de journalisation
1100         r:trace1("Ceci est un message de journalisation de niveau
1101         trace") -- les niveaux valides vont de trace1 à trace8
1102         r:debug("Ceci est un message de journalisation de niveau debug")
1103         r:info("Ceci est un message de journalisation de niveau info")
1104         r:notice("Ceci est un message de journalisation de niveau notice")
1105         r:warn("Ceci est un message de journalisation de niveau warn")
1106         r:err("Ceci est un message de journalisation de niveau err")
1107         r:alert("Ceci est un message de journalisation de niveau alert")
1108         r:crit("Ceci est un message de journalisation de niveau crit")
1109         r:emerg("Ceci est un message de journalisation de niveau emerg")</pre>
1110
1111
1112 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1113 <div class="section">
1114 <h2><a name="apache2" id="apache2">Paquet apache2</a></h2>
1115 <p>Le paquet nommé <code>apache2</code> est fourni avec (au minimum) le
1116 contenu suivant :</p>
1117 <dl>
1118   <dt>apache2.OK</dt>
1119   <dd>Constante interne OK. Les gestionnaires renverront cette valeur
1120   s'ils ont traité la requête.</dd>
1121   <dt>apache2.DECLINED</dt>
1122   <dd>Constante interne DECLINED. Les gestionnaires renverront cette
1123   valeur s'ils n'ont pas l'intention de traiter la requête.</dd>
1124   <dt>apache2.DONE</dt>
1125   <dd>Constante interne DONE.</dd>
1126   <dt>apache2.version</dt>
1127   <dd>Chaîne contenant la version du serveur HTTP Apache</dd>
1128   <dt>apache2.HTTP_MOVED_TEMPORARILY</dt>
1129   <dd>Code d'état HTTP</dd>
1130   <dt>apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE</dt>
1131   <dd>Constantes internes utilisées par <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code></dd>
1132   <dt>apache2.AUTHZ_DENIED, apache2.AUTHZ_GRANTED, apache2.AUTHZ_NEUTRAL, apache2.AUTHZ_GENERAL_ERROR, apache2.AUTHZ_DENIED_NO_USER</dt>
1133   <dd>constantes internes utilisées par <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code></dd>
1134
1135 </dl>
1136 <p>Les autres codes d'état HTTP ne sont pas encore implémentés.</p>
1137 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1138 <div class="section">
1139 <h2><a name="modifying_buckets" id="modifying_buckets">Modification de contenu avec les filtres lua</a></h2>
1140
1141     <p>
1142     Les fonctions de filtrage implémentées via les directives <code class="directive"><a href="#luainputfilter">LuaInputFilter</a></code> ou <code class="directive"><a href="#luaoutputfilter">LuaOutputFilter</a></code> sont conçues comme des
1143     fonctions de 3ème phase non blocantes utilisant des sous-routines
1144     pour suspendre et reprendre l'exécution d'une fonction lorsque des
1145     paquets de données sont envoyés à la chaîne de filtrage. La
1146     structure de base d'une telle fonction est :
1147     </p>
1148     <pre class="prettyprint lang-lua">function filter(r)
1149     -- Nous indiquons tout d'abord que nous sommes prêts à recevoir des
1150     -- blocs de données.
1151     -- Avant ceci, nous pouvons définir notre environnement, tester
1152     -- certaines conditions, et, si nous le jugeons nécessaire, refuser le
1153     -- filtrage d'une requête :
1154     if something_bad then
1155         return -- Le filtrage est sauté
1156     end
1157     -- Sans se préoccuper des données que nous devons éventuellement ajouter, un arrêt est réalisé ici.
1158     -- Noter que les filtres de sortie sont les seuls capables d'ajouter des éléments au début des données.
1159     -- Les filtres en entrée peuvent ajouter des éléments à la fin des données au stade final.
1160
1161     coroutine.yield([optional header to be prepended to the content])
1162
1163     -- Après cet arrêt, nous allons recevoir d'autres blocs de données, un par un ;
1164     -- nous pouvons les traiter comme il nous plaît et procéder à la réponse.
1165     -- Ces blocs sont conservés dans la variable globale 'bucket', nous réalisons donc
1166     -- une boucle pour vérifier que 'bucket' n'est pas vide :
1167     while bucket ~= nil do
1168         local output = mangle(bucket) -- Do some stuff to the content
1169         coroutine.yield(output) -- Return our new content to the filter chain
1170     end
1171
1172     -- Une fois les blocs de données épuisés, 'bucket' est positionné à une valeur vide ('nil'),
1173     -- ce qui va nous faire sortir de cette boucle et nous amener à l'étape suivante.
1174     -- On peut ajouter ce qu'on veut à la fin des données à cette étape, qui constitue le dernier
1175     -- arrêt. Les filtres d'entrée comme de sortie peuvent servir à ajouter des éléments à la fin
1176     --  des données à cette étape.
1177     coroutine.yield([optional footer to be appended to the content])
1178 end</pre>
1179
1180 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1181 <div class="section">
1182 <h2><a name="databases" id="databases">Connectivité aux bases de données</a></h2>
1183
1184     <p>Mod_lua implémente une fonctionnalité basique de connexion aux
1185 bases de données permettant d'envoyer des requêtes ou d'exécuter des
1186 commandes auprès des moteurs de base de données les plus courants
1187 (mySQL, PostgreSQL, FreeTDS, ODBC, SQLite, Oracle), ainsi que mod_dbd.
1188     </p>
1189     <p>L'exemple suivant montre comment se connecter à une base de
1190 données et extraire des informations d'une table :</p>
1191     <pre class="prettyprint lang-lua">function handle(r)
1192     -- connexion à la base de données
1193     local database, err = r:dbacquire("mysql", "server=localhost,user=someuser,pass=somepass,dbname=mydb")
1194     if not err then
1195         -- Sélection de certaines informations
1196         local results, err = database:select(r, "SELECT `name`, `age` FROM `people` WHERE 1")
1197         if not err then
1198             local rows = results(0) -- extrait tous les enregistrements en mode synchrone
1199             for k, row in pairs(rows) do
1200                 r:puts( string.format("Name: %s, Age: %s&lt;br/&gt;", row[1], row[2]) )
1201             end
1202         else
1203             r:puts("Database query error: " .. err)
1204         end
1205         database:close()
1206     else
1207         r:puts("Connexion à la base de données impossible : " .. err)
1208     end
1209 end</pre>
1210
1211     <p>
1212     Pour utiliser <code class="module"><a href="../mod/mod_dbd.html">mod_dbd</a></code>, spécifiez
1213 <code>mod_dbd</code> comme type de base de données, ou laissez le champ
1214 vide :
1215     </p>
1216     <pre class="prettyprint lang-lua">local database = r:dbacquire("mod_dbd")</pre>
1217
1218     <h3><a name="database_object" id="database_object">L'objet database et ses méthodes</a></h3>
1219
1220         <p>L'objet database renvoyé par <code>dbacquire</code> possède
1221 les méthodes suivantes :</p>
1222         <p><strong>Sélection normale et requête vers une base de données
1223 :</strong></p>
1224     <pre class="prettyprint lang-lua">-- Exécution d'une requête et renvoie du nombre d'enregistrements
1225 affectés :
1226 local affected, errmsg = database:query(r, "DELETE FROM `tbl` WHERE 1")
1227
1228 -- Exécution d'une requête et renvoie du résultat qui peut être utilisé
1229 en mode synchrone ou asynchrone :
1230 local result, errmsg = database:select(r, "SELECT * FROM `people` WHERE 1")</pre>
1231
1232         <p><strong>Utilisation de requêtes préparées (recommandé) :</strong></p>
1233     <pre class="prettyprint lang-lua">-- Création et exécution d'une requête préparée :
1234 local statement, errmsg = database:prepare(r, "DELETE FROM `tbl` WHERE `age` &gt; %u")
1235 if not errmsg then
1236     local result, errmsg = statement:query(20) -- exécute la requête pour age &gt; 20
1237 end
1238
1239 -- Extrait une requête préparée depuis une directive DBDPrepareSQL :
1240 local statement, errmsg = database:prepared(r, "someTag")
1241 if not errmsg then
1242     local result, errmsg = statement:select("John Doe", 123) -- injecte les valeurs "John Doe" et 123 dans la requête
1243 end</pre>
1244
1245         <p><strong>Echappement de valeurs, fermeture de la base données,
1246 etc...</strong></p>
1247     <pre class="prettyprint lang-lua">-- Echappe une valeur pour pouvoir l'utiliser dans une requête :
1248 local escaped = database:escape(r, [["'|blabla]])
1249
1250 -- Ferme une base de données et libère les liens vers cette dernière :
1251 database:close()
1252
1253 -- Vérifie si une connexion à une base de données est en service et
1254 opérationnelle :
1255 local connected = database:active()</pre>
1256
1257
1258     <h3><a name="result_sets" id="result_sets">Travail avec les jeux d'enregistrements renvoyés par les requêtes</a></h3>
1259
1260     <p>Les jeux d'enregistrements renvoyés par <code>db:select</code> ou par des
1261 requêtes préparées créées par <code>db:prepare</code> permettent de
1262 sélectionner des enregistrements en mode synchrone ou
1263 asynchrone, selon le nombre d'enregistrements spécifié :<br />
1264     <code>result(0)</code> sélectionne tous les enregistrements en mode
1265 synchrone en renvoyant une table d'enregistrements.<br />
1266     <code>result(-1)</code> sélectionne le prochain enregistrement disponible en
1267 mode asynchrone.<br />
1268     <code>result(N)</code> sélectionne l'enregistrement numéro
1269 <code>N</code> en mode asynchrone.
1270     </p>
1271     <pre class="prettyprint lang-lua">-- extrait un jeu d'enregistrements via une requête régulière :
1272 local result, err = db:select(r, "SELECT * FROM `tbl` WHERE 1")
1273
1274 local rows = result(0) -- sélectionne tous les enregistrements en mode synchrone
1275 local row = result(-1) -- sélectionne le prochain enregistrement disponible en mode asynchrone
1276 local row = result(1234) -- sélectionne l'enregistrement 1234 en mode asynchrone
1277 local row = result(-1, true) -- Lit l'enregistrement suivant en utilisant les noms d'enregistrements comme index.</pre>
1278
1279     <p>Il est possible de construire une fonction qui renvoie une
1280 fonction itérative permettant de traiter tous les enregistrement en mode
1281 synchrone ou asynchrone selon la valeur de l'argument async :
1282     </p>
1283     <pre class="prettyprint lang-lua">function rows(resultset, async)
1284     local a = 0
1285     local function getnext()
1286         a = a + 1
1287         local row = resultset(-1)
1288         return row and a or nil, row
1289     end
1290     if not async then
1291         return pairs(resultset(0))
1292     else
1293         return getnext, self
1294     end
1295 end
1296
1297 local statement, err = db:prepare(r, "SELECT * FROM `tbl` WHERE `age` &gt; %u")
1298 if not err then
1299      -- sélectionne des enregistrements en mode asynchrone :
1300     local result, err = statement:select(20)
1301     if not err then
1302         for index, row in rows(result, true) do
1303             ....
1304         end
1305     end
1306
1307      -- sélectionne des enregistrements en mode synchrone :
1308     local result, err = statement:select(20)
1309     if not err then
1310         for index, row in rows(result, false) do
1311             ....
1312         end
1313     end
1314 end</pre>
1315
1316
1317     <h3><a name="closing_databases" id="closing_databases">Fermeture d'une connexion à une base de données</a></h3>
1318
1319
1320     <p>Lorsqu'elles ne sont plus utilisées, les connexions aux bases de
1321 données doivent être fermées avec <code>database:close()</code>. Si vous
1322 ne les fermez pas manuellement, mod_lua les fermera peut-être en tant
1323 que résidus collectés, mais si ce n'est pas le cas, vous pouvez finir
1324 pas avoir trop de connexions vers la base de données inutilisées. Les
1325 deux mesures suivantes sont pratiquement identiques :
1326     </p>
1327     <pre class="prettyprint lang-lua">-- Méthode 1 : fermeture manuelle de la connexion
1328 local database = r:dbacquire("mod_dbd")
1329 database:close() -- c'est tout
1330
1331 -- Méthode 2 : on laisse le collecteur de résidus la fermer
1332 local database = r:dbacquire("mod_dbd")
1333 database = nil -- on coupe le lien
1334 collectgarbage() -- fermeture de la connexion par le collecteur de résidus</pre>
1335
1336
1337     <h3><a name="database_caveat" id="database_caveat">Précautions à prendre lorsque l'on travaille avec les bases
1338 de données</a></h3>
1339
1340     <p>Bien que les fonctions <code>query</code> et <code>run</code>
1341 soient toujours disponibles, il est recommandé d'utiliser des requêtes
1342 préparées chaque fois que possible, afin d'une part d'optimiser les
1343 performances (si votre connexion reste longtemps en vie), et d'autre part
1344 minimiser le risque d'attaques par injection SQL. Les fonctions
1345 <code>run</code> et <code>query</code> ne doivent être utilisées que
1346 lorsque la requête ne contient pas de variables (requête statique). Dans
1347 le cas des requêtes dynamiques, utilisez <code>db:prepare</code> ou
1348 <code>db:prepared</code>.
1349     </p>
1350
1351
1352 </div>
1353 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1354 <div class="directive-section"><h2><a name="luaauthzprovider" id="luaauthzprovider">Directive</a> <a name="LuaAuthzProvider" id="LuaAuthzProvider">LuaAuthzProvider</a></h2>
1355 <table class="directive">
1356 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Branche une fonction fournisseur d'autorisation dans <code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code>
1357 </td></tr>
1358 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaAuthzProvider provider_name /path/to/lua/script.lua function_name</code></td></tr>
1359 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur</td></tr>
1360 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1361 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1362 <tr><th><a href="directive-dict.html#Compatibility">Compatibilité:</a></th><td>Disponible depuis la version 2.4.3 du serveur HTTP Apache</td></tr>
1363 </table>
1364 <p>Lorsqu'une fonction lua a été enregistrée en tant que fournisseur
1365 d'autorisation, elle peut être appelée via la directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> :</p>
1366
1367
1368 <pre class="prettyprint lang-config">LuaRoot /usr/local/apache2/lua
1369 LuaAuthzProvider foo authz.lua authz_check_foo
1370 &lt;Location "/"&gt;
1371   Require foo johndoe
1372 &lt;/Location&gt;</pre>
1373
1374 <pre class="prettyprint lang-lua">require "apache2"
1375 function authz_check_foo(r, who)
1376     if r.user ~= who then return apache2.AUTHZ_DENIED
1377     return apache2.AUTHZ_GRANTED
1378 end</pre>
1379
1380
1381
1382 </div>
1383 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1384 <div class="directive-section"><h2><a name="luacodecache" id="luacodecache">Directive</a> <a name="LuaCodeCache" id="LuaCodeCache">LuaCodeCache</a></h2>
1385 <table class="directive">
1386 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure le cache de code compilé.</td></tr>
1387 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaCodeCache stat|forever|never</code></td></tr>
1388 <tr><th><a href="directive-dict.html#Default">Défaut:</a></th><td><code>LuaCodeCache stat</code></td></tr>
1389 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1390 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1391 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1392 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1393 </table><p>
1394     Cette directive permet de définir le comportement du cache de code
1395     en mémoire. La valeur par défaut est stat ; dans ce cas, le script
1396     du niveau le plus haut (et pas les scripts inclus) est vérifié à
1397     chaque fois que ce fichier est nécessaire, et est rechargé si la
1398     date de modification est plus récente que celle du script déjà
1399     chargé. Les autres valeurs permettent respectivement de garder le
1400     fichier en cache perpétuellement (forever - jamais vérifié ni
1401     remplacé), ou de ne jamais le mettre en cache (never).</p>
1402
1403     <p>En général, les valeurs stat et forever sont utilisées pour un
1404     serveur en production, et les valeurs stat ou never pour un serveur
1405     en développement.</p>
1406
1407     <div class="example"><h3>Exemples :</h3><pre class="prettyprint lang-config">LuaCodeCache stat
1408 LuaCodeCache forever
1409 LuaCodeCache never</pre>
1410 </div>
1411
1412
1413 </div>
1414 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1415 <div class="directive-section"><h2><a name="luahookaccesschecker" id="luahookaccesschecker">Directive</a> <a name="LuaHookAccessChecker" id="LuaHookAccessChecker">LuaHookAccessChecker</a></h2>
1416 <table class="directive">
1417 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase access_checker du
1418 traitement de la requête</td></tr>
1419 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookAccessChecker  /chemin/vers/lua/script.lua  hook_function_name [early|late]</code></td></tr>
1420 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1421 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1422 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1423 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1424 <tr><th><a href="directive-dict.html#Compatibility">Compatibilité:</a></th><td>Le troisième argument optionnel est disponible depuis la
1425 version 2.3.15 du serveur HTTP Apache.</td></tr>
1426 </table>
1427 <p>Ajoute votre fonction d'accroche à la phase access_checker. Une
1428 fonction d'accroche access checker renvoie en général OK, DECLINED, ou
1429 HTTP_FORBIDDEN.</p>
1430 <div class="note"><h3>Ordonnancement</h3><p>Les arguments optionnels
1431    "early" ou "late" permettent de contrôler le moment auquel ce script
1432    s'exécute par rapport aux autres modules.</p></div>
1433
1434 </div>
1435 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1436 <div class="directive-section"><h2><a name="luahookauthchecker" id="luahookauthchecker">Directive</a> <a name="LuaHookAuthChecker" id="LuaHookAuthChecker">LuaHookAuthChecker</a></h2>
1437 <table class="directive">
1438 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase auth_checker du
1439 traitement de la requête</td></tr>
1440 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookAuthChecker  /chemin/vers/lua/script.lua hook_function_name [early|late]</code></td></tr>
1441 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1442 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1443 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1444 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1445 <tr><th><a href="directive-dict.html#Compatibility">Compatibilité:</a></th><td>Le troisième argument optionnel est disponible depuis la
1446 version 2.3.15 du serveur HTTP Apache.</td></tr>
1447 </table>
1448 <p>Invoque une fonction lua au cours de la phase auth_checker du
1449 traitement de la requête. Cette directive peut s'utiliser pour
1450 implémenter une vérification arbitraire de l'authentification et de
1451 l'autorisation. Voici un exemple très simple :
1452 </p>
1453 <pre class="prettyprint lang-lua">require 'apache2'
1454
1455 -- fonction d'accroche authcheck fictive
1456 -- Si la requête ne contient aucune donnée d'authentification, l'en-tête
1457 -- de la réponse est défini et un code 401 est renvoyé afin de demander au
1458 -- navigateur d'effectuer une authentification basique. Si la requête
1459 -- comporte des données d'authentification, elles ne sont pas vraiment
1460 -- consultées, mais on admet la prise en compte de l'utilisateur 'foo' et
1461 -- on la valide. On vérifie ensuite si l'utilisateur est bien 'foo' et on
1462 -- accepte la requête.
1463 function authcheck_hook(r)
1464
1465    -- recherche des informations d'authentification
1466    auth = r.headers_in['Authorization']
1467    if auth ~= nil then
1468      -- définition d'un utilisateur par défaut
1469      r.user = 'foo'
1470    end
1471
1472    if r.user == nil then
1473       r:debug("authcheck: user is nil, returning 401")
1474       r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
1475       return 401
1476    elseif r.user == "foo" then
1477       r:debug('user foo: OK')
1478    else
1479       r:debug("authcheck: user='" .. r.user .. "'")
1480       r.err_headers_out['WWW-Authenticate'] = 'Basic realm="WallyWorld"'
1481       return 401
1482    end
1483    return apache2.OK
1484 end</pre>
1485
1486 <div class="note"><h3>Ordonnancement</h3><p>Les arguments optionnels
1487    "early" ou "late" permettent de contrôler le moment auquel ce script
1488    s'exécute par rapport aux autres modules.</p></div>
1489
1490 </div>
1491 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1492 <div class="directive-section"><h2><a name="luahookcheckuserid" id="luahookcheckuserid">Directive</a> <a name="LuaHookCheckUserID" id="LuaHookCheckUserID">LuaHookCheckUserID</a></h2>
1493 <table class="directive">
1494 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase check_user_id du
1495 traitement de la requête</td></tr>
1496 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookCheckUserID  /path/to/lua/script.lua hook_function_name</code></td></tr>
1497 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1498 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1499 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1500 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1501 </table>
1502 </div>
1503 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1504 <div class="directive-section"><h2><a name="luahookfixups" id="luahookfixups">Directive</a> <a name="LuaHookFixups" id="LuaHookFixups">LuaHookFixups</a></h2>
1505 <table class="directive">
1506 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase de correction du
1507 traitement de la requête</td></tr>
1508 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookFixups  /chemin/vers/lua/script.lua hook_function_name</code></td></tr>
1509 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1510 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1511 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1512 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1513 </table>
1514 <p>
1515     Idem LuaHookTranslateName, mais s'exécute durant la phase de
1516     correction.
1517 </p>
1518
1519 </div>
1520 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1521 <div class="directive-section"><h2><a name="luahookinsertfilter" id="luahookinsertfilter">Directive</a> <a name="LuaHookInsertFilter" id="LuaHookInsertFilter">LuaHookInsertFilter</a></h2>
1522 <table class="directive">
1523 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase insert_filter du
1524 traitement de la requête</td></tr>
1525 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookInsertFilter  /chemin/vers/lua/script.lua hook_function_name</code></td></tr>
1526 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1527 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1528 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1529 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1530 </table><p>Non encore implémenté</p>
1531 </div>
1532 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1533 <div class="directive-section"><h2><a name="luahooklog" id="luahooklog">Directive</a> <a name="LuaHookLog" id="LuaHookLog">LuaHookLog</a></h2>
1534 <table class="directive">
1535 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Permet une insertion dans la phase de journalisation du
1536 traitement d'une requête</td></tr>
1537 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookLog  /path/to/lua/script.lua log_function_name</code></td></tr>
1538 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1539 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1540 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1541 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1542 </table>
1543 <p>
1544     Ce dispositif d'insertion simple permet d'exécuter une fonction
1545     lorsque httpd entre dans la phase de journalisation du traitement
1546     d'une requête. Vous pouvez ainsi ajouter des données à vos propres
1547     entrées de journalisation, manipuler les entrées du journal standard
1548     avant leur enregistrement ou empêcher l'enregistrement d'une entrée
1549     dans le journal. Pour empêcher l'enregistrement normal des entrées
1550     du journal, renvoyez simplement <code>apache2.DONE</code> dans votre
1551     gestionnaire de journalisation, ou au contraire, renvoyez
1552     <code>apache2.OK</code> pour que httpd effectue une journalisation
1553     normale.
1554 </p>
1555 <p>Exemple :</p>
1556 <pre class="prettyprint lang-config">LuaHookLog /path/to/script.lua logger</pre>
1557
1558 <pre class="prettyprint lang-lua">-- /path/to/script.lua --
1559 function logger(r)
1560     -- on joue à pile ou face :
1561     -- Si on obtient 1, on écrit dans notre propre journal Lua et on dit
1562     -- à httpd de ne pas enregistrer d'entrée dans le journal standard..
1563     -- Si on obtient 2, on nettoie un peu les données avant que httpd ne
1564     -- les enregistre dans le journal standard.
1565
1566     if math.random(1,2) == 1 then
1567         -- On effectue notre propre journalisation et le journal
1568         -- standard n'est pas alimenté
1569         local f = io.open("/foo/secret.log", "a")
1570         if f then
1571             f:write("Quelque chose de secret est arrivé à " .. r.uri .. "\n")
1572             f:close()
1573         end
1574         return apache2.DONE -- On dit à httpd de ne rien enregistrer
1575                             --dans le journal standard
1576     else
1577         r.uri = r.uri:gsub("somesecretstuff", "") -- nettoie les données
1578         return apache2.OK -- et httpd doit alors les enregistrer.
1579     end
1580 end</pre>
1581
1582
1583 </div>
1584 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1585 <div class="directive-section"><h2><a name="luahookmaptostorage" id="luahookmaptostorage">Directive</a> <a name="LuaHookMapToStorage" id="LuaHookMapToStorage">LuaHookMapToStorage</a></h2>
1586 <table class="directive">
1587 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase map_to_storage du
1588 traitement de la requête</td></tr>
1589 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookMapToStorage  /chemin/vers/lua/script.lua hook_function_name</code></td></tr>
1590 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1591 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1592 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1593 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1594 </table>
1595     <p>Identique à la directive
1596     <code class="directive">LuaHookTranslateName</code>, mais s'exécute à la
1597     phase map-to-storage du traitement de la requête. Les modules comme
1598     mod_cache agissent pendant cette phase, ce qui permet de présenter
1599     un exemple intéressant de ce que l'on peut faire ici :</p>
1600     <pre class="prettyprint lang-config">LuaHookMapToStorage /path/to/lua/script.lua check_cache</pre>
1601
1602     <pre class="prettyprint lang-lua">require"apache2"
1603 cached_files = {}
1604
1605 function read_file(filename)
1606     local input = io.open(filename, "r")
1607     if input then
1608         local data = input:read("*a")
1609         cached_files[filename] = data
1610         file = cached_files[filename]
1611         input:close()
1612     end
1613     return cached_files[filename]
1614 end
1615
1616 function check_cache(r)
1617     if r.filename:match("%.png$") then -- Ne concerne que les fichiers PNG
1618         local file = cached_files[r.filename] -- Vérifie les entrées du cache
1619         if not file then
1620             file = read_file(r.filename)  -- Lit le fichier vers le cache
1621         end
1622         if file then -- Si le fichier existe, on l'envoie
1623             r.status = 200
1624             r:write(file)
1625             r:info(("%s a été envoyé au client depuis le cache"):format(r.filename))
1626             return apache2.DONE -- cout-circuite le gestionnaire par défaut des fichiers PNG
1627         end
1628     end
1629     return apache2.DECLINED -- Si nous n'avons rien eu à faire, nous laissons les autres s'en charger
1630 end</pre>
1631
1632
1633
1634 </div>
1635 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1636 <div class="directive-section"><h2><a name="luahooktranslatename" id="luahooktranslatename">Directive</a> <a name="LuaHookTranslateName" id="LuaHookTranslateName">LuaHookTranslateName</a></h2>
1637 <table class="directive">
1638 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée à la phase du nom de
1639 traduction du traitement de la requête</td></tr>
1640 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookTranslateName  /chemin/vers/lua/script.lua  nom_fonction_hook [early|late]</code></td></tr>
1641 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel</td></tr>
1642 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1643 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1644 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1645 <tr><th><a href="directive-dict.html#Compatibility">Compatibilité:</a></th><td>Le troisième argument optionnel est disponible depuis la
1646 version 2.3.15 du serveur HTTP Apache.</td></tr>
1647 </table><p>
1648     Cette directive permet d'ajouter un point d'entrée (à
1649     APR_HOOK_MIDDLE) à la phase du nom de traduction du traitement de la
1650     requête. La fonction hook accepte un seul argument, le request_rec,
1651     et doit renvoyer un code d'état qui est soit un code d'erreur HTTP,
1652     ou une constante définie dans le module apache2 :  apache2.OK,
1653     apache2.DECLINED, ou apache2.DONE.</p>
1654
1655     <p>Pour ceux qui ne sont pas familiers avec les points d'entrée
1656     (hook), en gros, chaque hook sera invoqué jusqu'à ce que l'un
1657     d'entre eux renvoie apache2.OK. Si un hook n'effectuer pas la
1658     traduction, il doit juste renvoyer apache2.DECLINED. Si le
1659     traitement de la requête doit être interrompu, la valeur renvoyée
1660     doit être apache2.DONE.</p>
1661
1662     <p>Exemple :</p>
1663
1664 <pre class="prettyprint lang-config"># httpd.conf
1665 LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper</pre>
1666
1667
1668 <pre class="prettyprint lang-lua">-- /scripts/conf/hooks.lua --
1669 require "apache2"
1670 function silly_mapper(r)
1671     if r.uri == "/" then
1672         r.filename = "/var/www/home.lua"
1673         return apache2.OK
1674     else
1675         return apache2.DECLINED
1676     end
1677 end</pre>
1678
1679
1680    <div class="note"><h3>Contexte</h3><p>Cette directive ne peut être
1681    utilisée ni à l'intérieur d'une section <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> ou <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code>, ni dans un fichier htaccess.</p></div>
1682
1683    <div class="note"><h3>Ordonnancement</h3><p>Les arguments optionnels
1684    "early" ou "late" permettent de contrôler le moment auquel ce script
1685    s'exécute par rapport aux autres modules.</p></div>
1686
1687 </div>
1688 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1689 <div class="directive-section"><h2><a name="luahooktypechecker" id="luahooktypechecker">Directive</a> <a name="LuaHookTypeChecker" id="LuaHookTypeChecker">LuaHookTypeChecker</a></h2>
1690 <table class="directive">
1691 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la phase type_checker du
1692 traitement de la requête</td></tr>
1693 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaHookTypeChecker  /chemin/vers/lua/script.lua hook_function_name</code></td></tr>
1694 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1695 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1696 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1697 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1698 </table><p>
1699     Cette directive fournit un point d'entrée pour la phase
1700     type_checker du traitement de la requête. Cette phase
1701     correspond au moment où la requête se voit assigner un type et un
1702     gestionnaire de contenu, et peut donc être utilisée pour modifier le
1703     type et le gestionnaire en fonction de l'entrée :
1704     </p>
1705     <pre class="prettyprint lang-config">LuaHookTypeChecker "/path/to/lua/script.lua" type_checker</pre>
1706
1707     <pre class="prettyprint lang-lua">    function type_checker(r)
1708         if r.uri:match("%.to_gif$") then -- foo.png.to_gif convient
1709             r.content_type = "image/gif" -- affectation du type image/gif
1710             r.handler = "gifWizard"      -- force le traitement de la requête par le module gifWizard
1711             r.filename = r.uri:gsub("%.to_gif$", "") -- corrige le nom du fichier demandé
1712             return apache2.OK
1713         end
1714
1715         return apache2.DECLINED
1716     end</pre>
1717
1718
1719 </div>
1720 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1721 <div class="directive-section"><h2><a name="luainherit" id="luainherit">Directive</a> <a name="LuaInherit" id="LuaInherit">LuaInherit</a></h2>
1722 <table class="directive">
1723 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Contrôle la manière dont les sections de configuration
1724 parentes sont fusionnées dans les enfants</td></tr>
1725 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaInherit none|parent-first|parent-last</code></td></tr>
1726 <tr><th><a href="directive-dict.html#Default">Défaut:</a></th><td><code>LuaInherit parent-first</code></td></tr>
1727 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1728 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1729 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1730 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1731 <tr><th><a href="directive-dict.html#Compatibility">Compatibilité:</a></th><td>Versions 2.4.0 et supérieures</td></tr>
1732 </table><p>Par défaut, si des directives LuaHook* se trouvent dans
1733     des sections de configuration Directory ou Location qui se
1734     chevauchent, les scripts
1735     définis dans les sections les plus spécifiques s'exécutent
1736     <em>après</em> ceux définis dans les sections plus génériques
1737     (LuaInherit parent-first). Vous pouvez inverser cet ordre, ou faire
1738     en sorte que le contexte parent ne s'applique pas du tout.</p>
1739
1740     <p>Jusqu'aux versions 2.3.x, le comportement par défaut consistait à
1741     ignorer les directives LuaHook* situées dans les sections de
1742     configuration parentes.</p>
1743 </div>
1744 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1745 <div class="directive-section"><h2><a name="luainputfilter" id="luainputfilter">Directive</a> <a name="LuaInputFilter" id="LuaInputFilter">LuaInputFilter</a></h2>
1746 <table class="directive">
1747 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit une fonction Lua pour le filtrage en entrée</td></tr>
1748 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaInputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
1749 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur</td></tr>
1750 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1751 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1752 <tr><th><a href="directive-dict.html#Compatibility">Compatibilité:</a></th><td>Disponible depuis la version 2.4.5 du serveur HTTP
1753 Apache</td></tr>
1754 </table>
1755 <p>Cette directive permet d'ajouter un filtre en entrée sous la forme
1756 d'une fonction Lua. A l'instar des filtres en sorties, les filtres en
1757 entrée fonctionnent comme des sous-routines, intervenant dans un premier
1758 temps avant l'envoi du contenu des tampons, puis chaque fois qu'un
1759 paquet de données doit être transmis à la chaîne, et éventuellement
1760 produisant toute donnée à ajouter aux données en entrée. La variable
1761 globale <code>bucket</code> contient les paquets de données tels qu'ils
1762 sont transmis au script Lua :
1763 </p>
1764
1765 <pre class="prettyprint lang-config">LuaInputFilter myInputFilter /www/filter.lua input_filter
1766 &lt;Files "*.lua"&gt;
1767   SetInputFilter myInputFilter
1768 &lt;/Files&gt;</pre>
1769
1770 <pre class="prettyprint lang-lua">--[[
1771     Exemple de filtre en entrée qui convertit toutes les données POST en
1772     majuscules.
1773 ]]--
1774 function input_filter(r)
1775     print("luaInputFilter called") -- pour débogage
1776     coroutine.yield() -- attend des paquets de données
1777     while bucket do -- Pour chaque paquet, faire ...
1778         local output = string.upper(bucket) -- Convertit toutes les données POST en majuscules
1779         coroutine.yield(output) -- Envoie les données traitées à la chaîne de filtrage
1780     end
1781     -- plus aucune donnée à traiter.
1782     coroutine.yield("&amp;filterSignature=1234") -- Ajoute une signature à la fin
1783 end</pre>
1784
1785 <p>
1786 Le filtre en entrée peut interdire ou sauter un filtre s'il est
1787 considéré comme indésirable :
1788 </p>
1789 <pre class="prettyprint lang-lua">function input_filter(r)
1790     if not good then
1791         return -- Empêche tout simplement le filtrage et transmet le contenu original
1792     end
1793     coroutine.yield() -- attend des paquets de données
1794     ...               -- insert les filtres ici
1795 end</pre>
1796
1797 <p>
1798 Voir "<a href="#modifying_buckets">Modification de contenu avec les
1799 filtres Lua</a>" pour plus de détails.
1800 </p>
1801
1802 </div>
1803 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1804 <div class="directive-section"><h2><a name="luamaphandler" id="luamaphandler">Directive</a> <a name="LuaMapHandler" id="LuaMapHandler">LuaMapHandler</a></h2>
1805 <table class="directive">
1806 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Met en correspondance un chemin avec un gestionnaire lua</td></tr>
1807 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaMapHandler modele-uri /chemin/vers/lua/script.lua
1808 [nom-fonction]</code></td></tr>
1809 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1810 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1811 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1812 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1813 </table>
1814     <p>Cette directive permet de faire correspondre un modèle d'uri avec
1815     une fonction de gestionnaire située dans un fichier spécifique. Elle
1816     utilise les expressions rationnelles PCRE pour mettre en
1817     correspondance l'uri, et supporte les groupes de correspondance
1818     d'interpolation dans le chemin du fichier et le nom de la fonction.
1819     Prenez garde aux problèmes de sécurité en écrivant vos expressions
1820     rationnelles.</p>
1821    <div class="example"><h3>Exemples :</h3><pre class="prettyprint lang-config">LuaMapHandler /(\w+)/(\w+) /scripts/$1.lua handle_$2</pre>
1822 </div>
1823         <p>Cette directive va faire correspondre des uri comme
1824         /photos/show?id=9 au fichier /scripts/photos.lua, et invoquera la
1825         fonction de gestionnaire handle_show au niveau de la vm lua
1826         après chargement de ce fichier.</p>
1827
1828 <pre class="prettyprint lang-config">LuaMapHandler /bingo /scripts/wombat.lua</pre>
1829
1830         <p>Cette directive invoquera la fonction "handle" qui est la
1831         valeur par défaut si aucun nom de fonction spécifique n'est
1832         spécifié.</p>
1833
1834 </div>
1835 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1836 <div class="directive-section"><h2><a name="luaoutputfilter" id="luaoutputfilter">Directive</a> <a name="LuaOutputFilter" id="LuaOutputFilter">LuaOutputFilter</a></h2>
1837 <table class="directive">
1838 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit une fonction Lua pour le filtrage de contenu en
1839 sortie</td></tr>
1840 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaOutputFilter filter_name /path/to/lua/script.lua function_name</code></td></tr>
1841 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur</td></tr>
1842 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1843 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1844 <tr><th><a href="directive-dict.html#Compatibility">Compatibilité:</a></th><td>Disponible à partir de la version 2.4.5 du serveur HTTP
1845 Apache</td></tr>
1846 </table>
1847 <p>&gt;Cette directive permet d'ajouter un filtre en sortie sous la forme
1848 d'une fonction Lua. A l'instar des filtres en sorties, les filtres en
1849 entrée fonctionnent comme des sous-routines, intervenant dans un premier
1850 temps avant l'envoi du contenu des tampons, puis chaque fois qu'un
1851 paquet de données doit être transmis à la chaîne, et éventuellement
1852 produisant toute donnée à ajouter aux données en sortie. La variable
1853 globale <code>bucket</code> contient les paquets de données tels qu'ils
1854 sont transmis au script Lua :
1855 </p>
1856
1857 <pre class="prettyprint lang-config">LuaOutputFilter myOutputFilter /www/filter.lua output_filter
1858 &lt;Files "*.lua"&gt;
1859   SetOutputFilter myOutputFilter
1860 &lt;/Files&gt;</pre>
1861
1862 <pre class="prettyprint lang-lua">--[[
1863     Exemple de filtre en sortie qui échappe toutes les entités HTML en
1864     sortie
1865 ]]--
1866 function output_filter(r)
1867     coroutine.yield("(Handled by myOutputFilter)&lt;br/&gt;\n") -- Ajoute des données au début de la sortie,
1868                                                                 -- puis attend des paquets de données à traiter
1869     while bucket do -- Pour chaque paquet, faire ...
1870         local output = r:escape_html(bucket) -- Echappe les données en sortie
1871         coroutine.yield(output) -- Envoie les données traitées à la chaîne
1872     end
1873     -- plus aucune donnée à traiter.
1874 end</pre>
1875
1876 <p>
1877 Comme les filres en entrée, le filtre en sortie peut interdire ou sauter un filtre s'il est
1878 considéré comme indésirable :
1879 </p>
1880 <pre class="prettyprint lang-lua">function output_filter(r)
1881     if not r.content_type:match("text/html") then
1882         return -- Empêche tout simplement le filtrage et transmet le contenu original
1883     end
1884     coroutine.yield() -- attend des paquets de données
1885     ...               -- insert les filtres ici
1886 end</pre>
1887
1888 <div class="note"><h3>Les filtres Lua avec <code class="module"><a href="../mod/mod_filter.html">mod_filter</a></code></h3>
1889 <p>Lorsqu'on utilise un filtre Lua comme fournisseur sous-jacent via la
1890 directive <code class="directive"><a href="../mod/mod_filter.html#filterprovider">FilterProvider</a></code>, le
1891 filtrage ne fonctionnera que si <var>filter-name</var> est identique à
1892 <var>provider-name</var>.
1893 </p> </div>
1894
1895 <p>
1896 Voir "<a href="#modifying_buckets">Modification de contenu avec les
1897 filtres Lua</a>" pour plus de détails.
1898 </p>
1899
1900
1901 </div>
1902 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1903 <div class="directive-section"><h2><a name="luapackagecpath" id="luapackagecpath">Directive</a> <a name="LuaPackageCPath" id="LuaPackageCPath">LuaPackageCPath</a></h2>
1904 <table class="directive">
1905 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ajoute un répertoire au package.cpath de lua</td></tr>
1906 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaPackageCPath /chemin/vers/include/?.soa</code></td></tr>
1907 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1908 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1909 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1910 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1911 </table>
1912     <p>Cette directive permet d'ajouter un chemin à la liste des chemins
1913     de recherche des bibliothèques partagées de lua. Ceci modifie le
1914     package.cpath dans les vms lua.</p>
1915
1916
1917 </div>
1918 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1919 <div class="directive-section"><h2><a name="luapackagepath" id="luapackagepath">Directive</a> <a name="LuaPackagePath" id="LuaPackagePath">LuaPackagePath</a></h2>
1920 <table class="directive">
1921 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ajoute un répertoire au package.path de lua</td></tr>
1922 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaPackagePath /chemin/vers/include/?.lua</code></td></tr>
1923 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1924 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1925 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1926 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1927 </table><p>Cette directive permet d'ajouter un chemin à la liste des
1928     chemins de recherche du module lua. Elle suit les mêmes conventions
1929     que lua. Ceci modifie le package.path dans les vms lua.</p>
1930
1931     <div class="example"><h3>Exemples :</h3><pre class="prettyprint lang-config">LuaPackagePath /scripts/lib/?.lua
1932 LuaPackagePath /scripts/lib/?/init.lua</pre>
1933 </div>
1934
1935 </div>
1936 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1937 <div class="directive-section"><h2><a name="luaquickhandler" id="luaquickhandler">Directive</a> <a name="LuaQuickHandler" id="LuaQuickHandler">LuaQuickHandler</a></h2>
1938 <table class="directive">
1939 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Fournit un point d'entrée pour la gestion rapide du
1940 traitement de la requête</td></tr>
1941 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaQuickHandler /path/to/script.lua hook_function_name</code></td></tr>
1942 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1943 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1944 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1945 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1946 </table>
1947     <p>Cette phase s'exécute juste après l'attribution de la requête à
1948     un serveur virtuel, et permet d'effectuer certains traitements avant
1949     le déroulement des autres phases, ou de servir une requête sans
1950     avoir à la traduire, l'associer à un espace de stockage, etc...
1951     Comme cette phase s'exécute avant toute autre, les directives telles
1952     que <code class="directive"><a href="../mod/core.html#location">&lt;Location&gt;</a></code> ou
1953     <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> ne
1954     sont pas encore prises en compte, car Les URI n'ont pas encore été
1955     entièrement interprétés.
1956     </p>
1957    <div class="note"><h3>Contexte</h3><p>Cette directive ne peut être
1958    utilisée ni à l'intérieur d'une section <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> ou <code class="directive"><a href="../mod/core.html#files">&lt;Files&gt;</a></code>, ni dans un fichier htaccess.</p></div>
1959
1960 </div>
1961 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1962 <div class="directive-section"><h2><a name="luaroot" id="luaroot">Directive</a> <a name="LuaRoot" id="LuaRoot">LuaRoot</a></h2>
1963 <table class="directive">
1964 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Spécifie le chemin de base pour la résolution des chemins
1965 relatifs dans les directives de mod_lua</td></tr>
1966 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaRoot /chemin/vers/un/répertoire</code></td></tr>
1967 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1968 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1969 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1970 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1971 </table>
1972     <p>Cette directive permet de spécifier le chemin de base qui sera
1973     utilisé pour évaluer tous les chemins relatifs dans mod_lua. En
1974     l'absence de cette directive, les chemins relatifs sont résolus par
1975     rapport au répertoire de travail courant, ce qui ne sera pas
1976     toujours approprié pour un serveur.</p>
1977
1978 </div>
1979 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
1980 <div class="directive-section"><h2><a name="luascope" id="luascope">Directive</a> <a name="LuaScope" id="LuaScope">LuaScope</a></h2>
1981 <table class="directive">
1982 <tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Une valeur parmi once, request, conn, thread -- la valeur par défaut est once</td></tr>
1983 <tr><th><a href="directive-dict.html#Syntax">Syntaxe:</a></th><td><code>LuaScope once|request|conn|thread|server [min] [max]</code></td></tr>
1984 <tr><th><a href="directive-dict.html#Default">Défaut:</a></th><td><code>LuaScope once</code></td></tr>
1985 <tr><th><a href="directive-dict.html#Context">Contexte:</a></th><td>configuration du serveur, serveur virtuel, répertoire, .htaccess</td></tr>
1986 <tr><th><a href="directive-dict.html#Override">AllowOverride:</a></th><td>All</td></tr>
1987 <tr><th><a href="directive-dict.html#Status">Statut:</a></th><td>Expérimental</td></tr>
1988 <tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_lua</td></tr>
1989 </table>
1990     <p>Cette directive permet de spécifier la durée de vie de
1991     l'interpréteur Lua qui sera utilisé dans ce "répertoire". La valeur
1992     par défaut est "once".</p>
1993
1994    <dl>
1995     <dt>once:</dt> <dd>utilise l'interpréteur une fois.</dd>
1996
1997     <dt>request:</dt> <dd>utilise l'interpréteur pour traiter tout ce
1998     qui est basé sur le même fichier dans la requête, et qui se trouve
1999     aussi dans la portée de la requête.</dd>
2000
2001     <dt>conn:</dt> <dd>idem request, mais attaché à connection_rec</dd>
2002
2003     <dt>thread:</dt> <dd>Utilise l'interpréteur pendant toute la durée
2004     de vie du thread qui traite la requête (disponible seulement avec
2005     les MPMs threadés).</dd>
2006
2007     <dt>server:</dt>  <dd>Le comportement est ici différent, car la
2008     portée du serveur présente une durée de vie assez longue, et
2009     plusieurs threads vont partager le même server_rec. Pour gérer tout
2010     ceci, les états lua du serveur sont stockés dans une liste de ressources
2011     apr. Les arguments <code>min</code> et <code>max</code> permettent
2012     de spécifier les nombres minimaux et maximaux d'états lua à stocker
2013     dans la liste.</dd>
2014    </dl>
2015    <p>En général, les portées <code>thread</code> et <code>server</code>
2016    sont 2 à 3 fois plus rapides que les autres, car elles n'ont pas besoin
2017    de régénérer de nouveaux états Lua à chaque requête (comme c'est le
2018    cas avec le MPM event, où même les connexions persistantes utilisent un
2019    nouveau thread pour chaque requête). Si vous pensez que vos scripts
2020    n'auront pas de problème s'il réutilisent un état, alors les portées
2021    <code>thread</code> ou <code>server</code> doivent être utilisées car
2022    elles présenteront de meilleures performances. Alors que la portée
2023    <code>thread</code> fournira les réponses les plus rapides, la portée
2024    <code>server</code> utilisera moins de mémoire car les états sont
2025    rassemblés dans des jeux, permettant par exemple à 1000 threads de
2026    partager 100 états Lua, ne nécessitant ainsi que 10% de la mémoire
2027    requise par la portée <code>thread</code>.
2028     </p>
2029
2030 </div>
2031 </div>
2032 <div class="bottomlang">
2033 <p><span>Langues Disponibles: </span><a href="../en/mod/mod_lua.html" hreflang="en" rel="alternate" title="English">&nbsp;en&nbsp;</a> |
2034 <a href="../fr/mod/mod_lua.html" title="Français">&nbsp;fr&nbsp;</a></p>
2035 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Commentaires</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&amp;A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
2036 <script type="text/javascript"><!--//--><![CDATA[//><!--
2037 var comments_shortname = 'httpd';
2038 var comments_identifier = 'http://httpd.apache.org/docs/trunk/mod/mod_lua.html';
2039 (function(w, d) {
2040     if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
2041         d.write('<div id="comments_thread"><\/div>');
2042         var s = d.createElement('script');
2043         s.type = 'text/javascript';
2044         s.async = true;
2045         s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
2046         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
2047     }
2048     else {
2049         d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
2050     }
2051 })(window, document);
2052 //--><!]]></script></div><div id="footer">
2053 <p class="apache">Copyright 2016 The Apache Software Foundation.<br />Autorisé sous <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
2054 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossaire</a> | <a href="../sitemap.html">Plan du site</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
2055 if (typeof(prettyPrint) !== 'undefined') {
2056     prettyPrint();
2057 }
2058 //--><!]]></script>
2059 </body></html>