mod_lua.html.fr 98.1 KB
Newer Older
powelld's avatar
powelld committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="fr" xml:lang="fr"><head>
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
<!--
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
              This file is generated from xml source: DO NOT EDIT
        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
      -->
<title>mod_lua - Serveur Apache HTTP Version 2.4</title>
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
<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" />
<script src="../style/scripts/prettify.min.js" type="text/javascript">
</script>

<link href="../images/favicon.ico" rel="shortcut icon" /></head>
<body>
<div id="page-header">
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.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>
<p class="apache">Serveur Apache HTTP Version 2.4</p>
<img alt="" src="../images/feather.png" /></div>
<div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
<div id="path">
<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.4</a> &gt; <a href="./">Modules</a></div>
<div id="page-content">
<div id="preamble"><h1>Module Apache mod_lua</h1>
<div class="toplang">
<p><span>Langues Disponibles: </span><a href="../en/mod/mod_lua.html" hreflang="en" rel="alternate" title="English">&nbsp;en&nbsp;</a> |
<a href="../fr/mod/mod_lua.html" title="Franais">&nbsp;fr&nbsp;</a></p>
</div>
<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Fournit des points d'entre Lua dans diffrentes parties du
traitement des requtes httpd</td></tr>
<tr><th><a href="module-dict.html#Status">Statut:</a></th><td>Exprimental</td></tr>
<tr><th><a href="module-dict.html#ModuleIdentifier">IdentificateurdeModule:</a></th><td>lua_module</td></tr>
<tr><th><a href="module-dict.html#SourceFile">FichierSource:</a></th><td>mod_lua.c</td></tr>
<tr><th><a href="module-dict.html#Compatibility">Compatibilit:</a></th><td>versions 2.3 et suprieures</td></tr></table>
<h3>Sommaire</h3>

<p>Ce module permet d'ajouter au serveur des extensions sous forme de
scripts crits dans le langage de programmation Lua.
<code class="module"><a href="../mod/mod_lua.html">mod_lua</a></code> fournit de nombreuses extensions
(hooks) disponibles avec les modules natifs du serveur HTTP Apache,
comme les associations de requtes  des fichiers, la gnration de
rponses dynamiques, le contrle d'accs, l'authentification et
l'autorisation.</p>

<p>Vous trouverez davantage d'informations  propos du langage de
programmation Lua sur <a href="http://www.lua.org/">le site web de
Lua</a>.</p>

<div class="note"><code>mod_lua</code> est encore au stade exprimental. Son mode
d'utilisation et son comportement pourront changer  tout moment jusqu'
ce qu'il passe au stade stable, et ce mme entre deux versions stables
2.4.x. N'oublez pas de consulter le fichier CHANGES avant toute mise 
jour.</div>

<div class="warning"><h3>Avertissement</h3>
<p>Ce module possde une grande capacit d'action sur le fonctrionnement
de httpd, ce qui lui confre une grande puissance, mais peut aussi
induire un risque de scurit. Il est dconseill d'utiliser ce module
sur un serveur partag avec des utilisateurs auxquels vous ne pouvez pas
accorder une confiance absolue, car il peut permettre de modifier le
fonctionnement interne de httpd.</p>
</div>

</div>
<div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><h3>Sujets</h3>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#basicconf">Configuration de base</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#writinghandlers">Ecrire des gestionnaires</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#writingauthzproviders">Ecriture de fournisseurs d'autorisation</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#writinghooks">Ecriture de fonctions d'accroche
(hooks)</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#datastructures">Structures de donnes</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#functions">Mthodes de l'objet request_rec</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#logging">Fonctions de journalisation</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#apache2">Paquet apache2</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#modifying_buckets">Modification de contenu avec les filtres lua</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#databases">Connectivit aux bases de donnes</a></li>
</ul><h3 class="directives">Directives</h3>
<ul id="toc">
<li><img alt="" src="../images/down.gif" /> <a href="#luaauthzprovider">LuaAuthzProvider</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luacodecache">LuaCodeCache</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookaccesschecker">LuaHookAccessChecker</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookauthchecker">LuaHookAuthChecker</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookcheckuserid">LuaHookCheckUserID</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookfixups">LuaHookFixups</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookinsertfilter">LuaHookInsertFilter</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahooklog">LuaHookLog</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahookmaptostorage">LuaHookMapToStorage</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahooktranslatename">LuaHookTranslateName</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luahooktypechecker">LuaHookTypeChecker</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luainherit">LuaInherit</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luainputfilter">LuaInputFilter</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luamaphandler">LuaMapHandler</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luaoutputfilter">LuaOutputFilter</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luapackagecpath">LuaPackageCPath</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luapackagepath">LuaPackagePath</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luaquickhandler">LuaQuickHandler</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luaroot">LuaRoot</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#luascope">LuaScope</a></li>
</ul>
<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">Problmes 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>
<ul class="seealso">
<li><a href="#comments_section">Commentaires</a></li></ul></div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="basicconf" id="basicconf">Configuration de base</a></h2>

<p>La directive de base pour le chargement du module est</p>

<pre class="prettyprint lang-config">LoadModule lua_module modules/mod_lua.so</pre>


<p>
<code>mod_lua</code> fournit un gestionnaire nomm
<code>lua-script</code> qui peut tre utilis avec une directive
<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> :</p>

<pre class="prettyprint lang-config">&lt;Files "*.lua"&gt;
    SetHandler lua-script
&lt;/Files&gt;</pre>


<p>
Ceci aura pour effet de faire traiter les requtes pour les fichiers
dont l'extension est <code>.lua</code> par <code>mod_lua</code> en
invoquant cette fonction de <code>gestion</code> de fichier.
</p>

<p>Pour plus de dtails, voir la directive
<code class="directive">LuaMapHandler</code>.
 </p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="writinghandlers" id="writinghandlers">Ecrire des gestionnaires</a></h2>
<p>Dans l'API du serveur HTTP Apache, un gestionnaire est une sorte de
point d'accroche (hook) spcifique responsable de la gnration de la
rponse. <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
<code class="module"><a href="../mod/mod_status.html">mod_status</a></code> sont des exemples de modules comportant un
gestionnaire.</p>

<p><code>mod_lua</code> cherche toujours  invoquer une fonction Lua pour le
gestionnaire, plutt que de simplement valuer le corps d'un script dans
le style de CGI. Une fonction de gestionnaire se prsente comme suit :</p>


<pre class="prettyprint lang-lua">
<strong>example.lua</strong><br />
-- exemple de gestionnaire

require "string"

--[[
     Il s'agit du nom de mthode par dfaut pour les gestionnaires Lua ;
     voir les noms de fonctions optionnels dans la directive
     LuaMapHandler pour choisir un point d'entre diffrent.
--]]
function handle(r)
    r.content_type = "text/plain"

    if r.method == 'GET' then
    	r:puts("Hello Lua World!\n")
        for k, v in pairs( r:parseargs() ) do
            r:puts( string.format("%s: %s\n", k, v) )
        end
    elseif r.method == 'POST' then
    	r:puts("Hello Lua World!\n")
        for k, v in pairs( r:parsebody() ) do
            r:puts( string.format("%s: %s\n", k, v) )
        end
    else
    elseif r.method == 'PUT' then
-- message d'erreur personnalis
        r:puts("Unsupported HTTP method " .. r.method)
	r.status = 405
        return apache2.OK
    else
-- message d'erreur ErrorDocument
        return 501
    end
    return apache2.OK
end</pre>


<p>
Ce gestionnaire se contente d'afficher les arguments cods d'un uri ou
d'un formulaire dans un page au format texte.
</p>

<p>
Cela signifie que vous pouvez (et tes encourag ) avoir plusieurs
gestionnaires (ou points d'entre, ou filtres) dans le mme script.
</p>

</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="writingauthzproviders" id="writingauthzproviders">Ecriture de fournisseurs d'autorisation</a></h2>


<p><code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> fournit une interface d'autorisation
de haut niveau bien plus facile  utiliser que dans les hooks
correspondants. Le premier argument de la directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code> permet de spcifier le
fournisseur d'autorisation  utiliser. Pour chaque directive <code class="directive"><a href="../mod/mod_authz_core.html#require">Require</a></code>,
<code class="module"><a href="../mod/mod_authz_core.html">mod_authz_core</a></code> appellera le fournisseur d'autorisation
spcifi, le reste de la ligne constituant les paramtres. Le
fournisseur considr va alors vrifier les autorisations et fournir le
rsultat dans une valeur de retour.</p>

<p>En gnral, le fournisseur authz est appel avant l'authentification.
S'il doit connatre le nom d'utilisateur authentifi (ou si
l'utilisateur est appel  tre authentifi), le fournisseur doit
renvoyer <code>apache2.AUTHZ_DENIED_NO_USER</code>, ce qui va
dclancher le processus d'authentification et un deuxime appel du
fournisseur authz.</p>

<p>La fonction du fournisseur authz ci-dessous accepte deux arguments,
une adresse IP et un nom d'utilisateur. Elle autorise l'accs dans le
cas o la requte provient de l'adresse IP spcifie, ou si
l'utilisateur authentifi correspond au second argument :</p>

<pre class="prettyprint lang-lua">
<strong>authz_provider.lua</strong><br />

require 'apache2'

function authz_check_foo(r, ip, user)
    if r.useragent_ip == ip then
        return apache2.AUTHZ_GRANTED
    elseif r.user == nil then
        return apache2.AUTHZ_DENIED_NO_USER
    elseif r.user == user then
        return apache2.AUTHZ_GRANTED
    else
        return apache2.AUTHZ_DENIED
    end
end</pre>


<p>La configuration suivante enregistre cette fonction en tant que
fournisseur <code>foo</code>, et la configure por l'URL <code>/</code> :</p>
<pre class="prettyprint lang-config">LuaAuthzProvider foo authz_provider.lua authz_check_foo
&lt;Location "/"&gt;
  Require foo 10.1.2.3 john_doe
&lt;/Location&gt;</pre>


</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="writinghooks" id="writinghooks">Ecriture de fonctions d'accroche
(hooks)</a></h2>

<p>Les fonctions d'accroche dterminent la manire dont les modules (et
les scripts Lua) participent au traitement des requtes. Chaque type
d'accroche propos par le serveur a un rle spcifique, comme
l'association de requtes au systme de fichiers, le contrle d'accs,
ou la dfinition de types MIME : </p>

<table class="bordered"><tr class="header">
        <th>Phase d'accroche</th>
        <th>Directive mod_lua</th>
        <th>Description</th>
    </tr>
<tr>
        <td>Gestionnaire rapide</td>
        <td><code class="directive"><a href="#luaquickhandler">LuaQuickHandler</a></code></td>
        <td>Il s'agit de la premire accroche appele lorsqu'une requte
	a t associe  un serveur ou un serveur virtuel.</td>
    </tr>
<tr class="odd">
        <td>Phase de traduction</td>
        <td><code class="directive"><a href="#luahooktranslatename">LuaHookTranslateName</a></code></td>
        <td>Cette phase traduit l'URI de la requte en nom de fichier
	sur le systme. Ce sont des modules comme
	<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
	interviennent au cours de cette phase.</td>
    </tr>
<tr>
        <td>Choix du lieu de stockage de la ressource</td>
        <td><code class="directive"><a href="#luahookmaptostorage">LuaHookMapToStorage</a></code></td>
        <td>Cette phase dfinit le lieu de stockage de la ressource :
	physique, en cache ou externe/mandat. Elle est assure par les
	modules de mandat ou de mise en cache.</td>
    </tr>
<tr class="odd">
        <td>Autorisation d'accs</td>
        <td><code class="directive"><a href="#luahookaccesschecker">LuaHookAccessChecker</a></code></td>
        <td>Cette phase vrifie si un client a l'autorisation d'accs 
	la ressource. Elle s'excute avant l'authentification de
	l'utisateur ; il faut donc tre prudent.
        </td>
    </tr>
<tr>
        <td>Vrification de l'identifiant utilisateur</td>
        <td><code class="directive"><a href="#luahookcheckuserid">LuaHookCheckUserID</a></code></td>
        <td>Cette phase vrifie l'identifiant de l'utilisateur ayant
	fait l'objet d'une ngociation.</td>
    </tr>
<tr class="odd">
        <td>Vrification de l'autorisation d'accs</td>
        <td><code class="directive"><a href="#luahookauthchecker">LuaHookAuthChecker</a></code>
	ou
            <code class="directive"><a href="#luaauthzprovider">LuaAuthzProvider</a></code></td>
        <td>Cette phase vrifie l'autorisation d'accs d'un utilisateur
	en fonction des ses paramtres de connexion, comme
	l'identifiant, le certificat, etc...
        </td>
    </tr>
<tr>
        <td>Vrification du type de la ressource</td>
        <td><code class="directive"><a href="#luahooktypechecker">LuaHookTypeChecker</a></code></td>
        <td>Cette phase assigne un type de contenu et un gestionnaire 
	la ressource.</td>
    </tr>
<tr class="odd">
        <td>Derniers rglages</td>
        <td><code class="directive"><a href="#luahookfixups">LuaHookFixups</a></code></td>
        <td>C'est la dernire phase avant l'activation des gestionnaires
	de contenu. Toute modification de dernire minute  la requte
	doit tre effectue ici.</td>
    </tr>
<tr>
        <td>Gestionnaire de contenu</td>
        <td>fichiers fx. <code>.lua</code> ou directive <code class="directive"><a href="#luamaphandler">LuaMapHandler</a></code></td>
        <td>C'est durant cette phase que le contenu est trait. Les
	fichiers sont lus, interprts, certains sont excuts, et le
	rsultat obtenu est envoy au client.</td>
    </tr>
<tr class="odd">
        <td>Journalisation</td>
        <td><code class="directive"><a href="#luahooklog">LuaHookLog</a></code></td>
        <td>Lorsqu'une requte a t traite, plusieurs phases de
	journalisation interviennent, et enregistrent leurs rsultats
	dans les fichiers d'erreur ou d'accs. Mod_lua peut
	s'intercaler au dpart de ce processus et ainsi contrler la
	journalisation.</td>
    </tr>
</table>

<p>Les fonctions d'accroche reoivent l'objet de la requte comme seul
argument (sauf LuaAuthzProvider qui reoit aussi des arguments en
provenance de la directive Require). Elles peuvent renvoyer une valeur,
selon la fonction, mais il s'agit en gnral d'un
code d'tat HTTP ou des valeurs OK, DONE, ou DECLINED,
que vous pouvez crire dans Lua sous la forme <code>apache2.OK</code>,
<code>apache2.DONE</code>, ou <code>apache2.DECLINED</code>.</p>


<pre class="prettyprint lang-lua">
<strong>translate_name.lua</strong><br />
-- exemple d'accroche qui rcrit un URI en chemin du systme de fichiers.

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.filename = r.document_root .. "/find_me.txt"
        return apache2.OK
    end
    -- on ne gre pas cette URL et on donne sa chance  un autre module
    return apache2.DECLINED
end</pre>



<pre class="prettyprint lang-lua">
<strong>translate_name2.lua</strong><br />
--[[ exemple d'accroche qui rcrit un URI vers un autre URI. Il renvoie
	un apache2.DECLINED pour permettre  un autre interprteur d'URL de
	travailler sur la substitution, y compris l'accroche translate_name
	de base dont les tables de correspondances se basent sur DocumentRoot.

     Note: utilisez le drapeau early/late de la directive pour
     l'excuter avant ou aprs mod_alias.
--]]

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.uri = "/find_me.txt"
        return apache2.DECLINED
    end
    return apache2.DECLINED
end</pre>

</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="datastructures" id="datastructures">Structures de donnes</a></h2>

<dl>
<dt>request_rec</dt>
        <dd>
        <p>request_rec est considre en tant que donne utilisateur.
	Elle possde une mtatable qui vous permet d'accomplir des
	choses intressantes. Pour la plus grande partie, elle possde
	les mmes champs que la structure request_rec, la
	plupart d'entre eux tant accessibles en lecture et criture (le
	contenu des champs de la table peut tre modifi, mais les
	champs eux-mmes ne peuvent pas tre tablis en tant que tables
	distinctes).</p>

	<table class="bordered"><tr class="header">
          <th><strong>Nom</strong></th>
          <th><strong>Type Lua</strong></th>
          <th><strong>Modifiable</strong></th>
	  <th><strong>Description</strong></th>
        </tr>
<tr>
          <td><code>allowoverrides</code></td>
          <td>string</td>
          <td>non</td>
          <td>L'option AllowOverride s'applique  la requte courante.</td>
        </tr>
<tr class="odd">
          <td><code>ap_auth_type</code></td>
          <td>string</td>
          <td>non</td>
	  <td>Ce champ contient le type d'authentification effectue
	  (par exemple <code>basic</code>)</td>
        </tr>
<tr>
          <td><code>args</code></td>
          <td>string</td>
          <td>oui</td>
	  <td>La chane de paramtres de la requte (par exemple
	  <code>foo=bar&amp;name=johnsmith</code>)</td>
        </tr>
<tr class="odd">
          <td><code>assbackwards</code></td>
          <td>boolean</td>
          <td>non</td>
	  <td>contient true s'il s'agit d'une requte de style HTTP/0.9
	  (par exemple <code>GET /foo</code> (sans champs d'en-tte) )</td>
        </tr>
<tr>
          <td><code>auth_name</code></td>
          <td>string</td>
          <td>non</td>
          <td>La chane d'identification utilise pour la vrification
	  de l'autorisation d'accs (si elle est disponible).</td>
        </tr>
<tr class="odd">
          <td><code>banner</code></td>
          <td>string</td>
          <td>non</td>
          <td>La bannire du serveur, par exemple <code>Apache HTTP
	  Server/2.4.3 openssl/0.9.8c</code></td>
        </tr>
<tr>
          <td><code>basic_auth_pw</code></td>
          <td>string</td>
          <td>non</td>
          <td>Le mot de passe pour l'authentification de base envoy
	  avec la requte, s'il existe</td>
        </tr>
<tr class="odd">
          <td><code>canonical_filename</code></td>
          <td>string</td>
          <td>non</td>
	  <td>Le nom de fichier canonique de la requte</td>
        </tr>
<tr>
          <td><code>content_encoding</code></td>
          <td>string</td>
          <td>non</td>
	  <td>Le type de codage du contenu de la requte courante</td>
        </tr>
<tr class="odd">
          <td><code>content_type</code></td>
          <td>string</td>
          <td>oui</td>
	  <td>Le type de contenu de la requte courante, tel qu'il a t
	  dtermin au cours de la phase type_check (par exemple
	  <code>image/gif</code> ou <code>text/html</code>)</td>
        </tr>
<tr>
          <td><code>context_prefix</code></td>
          <td>string</td>
          <td>non</td>
	  <td />
        </tr>
<tr class="odd">
          <td><code>context_document_root</code></td>
          <td>string</td>
          <td>non</td>
	  <td />
        </tr>
<tr>
          <td><code>document_root</code></td>
          <td>string</td>
          <td>non</td>
	  <td>La racine des documents du serveur</td>
        </tr>
<tr class="odd">
          <td><code>err_headers_out</code></td>
          <td>table</td>
          <td>non</td>
	  <td>L'en-tte MIME de l'environnement pour la rponse, crit
	  mme en cas d'erreur et conserv pendant les redirections
	  internes</td>
        </tr>
<tr>
          <td><code>filename</code></td>
          <td>string</td>
          <td>oui</td>
	  <td>Le nom de fichier correspondant  la requte, par exemple
	  /www/example.com/foo.txt. Il peut tre modifi au cours des
	  phases translate-name ou map-to-storage du traitement de la
	  requte pour permettre au gestionnaire par dfaut (ou aux
	  gestionnaires de script) de servir une version du fichier
	  autre que celle demande.</td>
        </tr>
<tr class="odd">
          <td><code>handler</code></td>
          <td>string</td>
          <td>oui</td>
	  <td>Le nom du <a href="../handler.html">gestionnaire</a> qui
	  doit traiter la requte, par exemple <code>lua-script</code>
	  si elle doit tre traite par mod_lua. Cette valeur est en
	  gnral dfinie 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
	  via mod_lua pour permettre  un autre gestionnaire de traiter
	  une requte spcifique qui ne serait pas traite par dfaut
	  par ce dernier.
            </td>
        </tr>
<tr>
	  <td><code>headers_in</code></td>
          <td>table</td>
          <td>oui</td>
	  <td>Les en-ttes MIME de l'environnement de la requte. Il
	  s'agit des en-ttes comme <code>Host, User-Agent,
	  Referer</code>, etc...</td>
        </tr>
<tr class="odd">
          <td><code>headers_out</code></td>
          <td>table</td>
          <td>oui</td>
	  <td>Les en-ttes MIME de l'environnement de la rponse.</td>
        </tr>
<tr>
          <td><code>hostname</code></td>
          <td>string</td>
          <td>non</td>
	  <td>Le nom d'hte, tel que dfini par l'en-tte
	  <code>Host:</code> ou par un URI complet.</td>
        </tr>
<tr class="odd">
          <td><code>is_https</code></td>
          <td>boolean</td>
          <td>non</td>
          <td>Indique si la requte  t faite via HTTPS</td>
        </tr>
<tr>
          <td><code>is_initial_req</code></td>
          <td>boolean</td>
          <td>non</td>
          <td>Indique si la requte courante est la requte initiale ou
	  une sous-requte.</td>
        </tr>
<tr class="odd">
          <td><code>limit_req_body</code></td>
          <td>number</td>
          <td>non</td>
          <td>La taille maximale du corps de la requte, ou 0 si aucune
	  limite.</td>
        </tr>
<tr>
	<td><code>log_id</code></td>
          <td>string</td>
          <td>non</td>
	  <td>L'identifiant de la requte dans les journaux d'accs ou
	  d'erreur.</td>
        </tr>
<tr class="odd">
          <td><code>method</code></td>
          <td>string</td>
          <td>non</td>
	  <td>La mthode de la requte, par exemple <code>GET</code> ou
	  <code>POST</code>.</td>
        </tr>
<tr>
          <td><code>notes</code></td>
          <td>table</td>
          <td>oui</td>
	  <td>Une liste de notes qui peuvent tre transmises d'un module
	   l'autre.</td>
        </tr>
<tr class="odd">
          <td><code>options</code></td>
          <td>string</td>
          <td>non</td>
          <td>La valeur de la directive Options pour la requte
	  courante.</td>
        </tr>
<tr>
          <td><code>path_info</code></td>
          <td>string</td>
          <td>non</td>
	  <td>La valeur de PATH_INFO extraite de la requte.</td>
        </tr>
<tr class="odd">
          <td><code>port</code></td>
          <td>number</td>
          <td>non</td>
          <td>Le port du serveur utilis par la requte.</td>
        </tr>
<tr>
          <td><code>protocol</code></td>
          <td>string</td>
          <td>non</td>
	  <td>Le protocole utilis, par exemple <code>HTTP/1.1</code></td>
        </tr>
<tr class="odd">
          <td><code>proxyreq</code></td>
          <td>string</td>
          <td>oui</td>
	  <td>Indique s'il s'agit d'une requte mandate ou non. Cette
	  valeur est en gnral dfinie au cours de la phase
	  post_read_request/translate_name du traitement de la requte.</td>
        </tr>
<tr>
	  <td><code>range</code></td>
          <td>string</td>
          <td>non</td>
	  <td>Le contenu de l'en-tte <code>Range:</code>.</td>
        </tr>
<tr class="odd">
          <td><code>remaining</code></td>
          <td>number</td>
          <td>non</td>
          <td>Le nombre d'octets du corps de la requte restant  lire.</td>
        </tr>
<tr>
          <td><code>server_built</code></td>
          <td>string</td>
          <td>non</td>
          <td>La date de compilation du serveur.</td>
        </tr>
<tr class="odd">
          <td><code>server_name</code></td>
          <td>string</td>
          <td>non</td>
          <td>Le nom du serveur pour cette requte.</td>
        </tr>
<tr>
          <td><code>some_auth_required</code></td>
          <td>boolean</td>
          <td>non</td>
          <td>Indique si une autorisation est/tait requise pour cette
	  requte.</td>
        </tr>
<tr class="odd">
          <td><code>subprocess_env</code></td>
          <td>table</td>
          <td>oui</td>
	  <td>Le jeu de variables d'environnement pour cette requte.</td>
        </tr>
<tr>
          <td><code>started</code></td>
          <td>number</td>
          <td>non</td>
          <td>Le moment o le serveur a t (re)dmarr, en secondes
	  depuis epoch (1er janvier 1970)</td>
        </tr>
<tr class="odd">
	  <td><code>status</code></td>
          <td>number</td>
          <td>oui</td>
	  <td>Le code de retour (courant) pour cette requte, par
	  exemple <code>200</code> ou <code>404</code>.</td>
        </tr>
<tr>
          <td><code>the_request</code></td>
          <td>string</td>
          <td>non</td>
	  <td>La chane de la requte telle qu'elle a t envoye par le
	  client, par exemple <code>GET /foo/bar HTTP/1.1</code>.</td>
        </tr>
<tr class="odd">
          <td><code>unparsed_uri</code></td>
          <td>string</td>
          <td>non</td>
	  <td>La partie URI non interprte de la requte</td>
        </tr>
<tr>
          <td><code>uri</code></td>
          <td>string</td>
          <td>oui</td>
	  <td>L'URI aprs interprtation par httpd</td>
        </tr>
<tr class="odd">
          <td><code>user</code></td>
          <td>string</td>
          <td>oui</td>
	  <td>Si une authentification a t effectue, nom de
	  l'utilisateur authentifi.</td>
        </tr>
<tr>
          <td><code>useragent_ip</code></td>
          <td>string</td>
          <td>non</td>
	  <td>L'adresse IP de l'agent qui a envoy la requte</td>
        </tr>
</table>
	</dd>
    </dl>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="functions" id="functions">Mthodes de l'objet request_rec</a></h2>

<p>L'objet request_rec possde (au minimum) les mthodes suivantes :</p>

<pre class="prettyprint lang-lua">r:flush()   -- vide le tampon de sortie
            -- Renvoie true si le vidage a t effectu avec succs,
	    -- false dans le cas contraire.

while nous_avons_des_donnes__envoyer do
    r:puts("Bla bla bla\n") -- envoi des donnes  envoyer vers le tampon
    r:flush() -- vidage du tampon (envoi au client)
    r.usleep(500000) -- mise en attente pendant 0.5 secondes et bouclage
end</pre>


<pre class="prettyprint lang-lua">r:addoutputfilter(name|function) -- ajoute un filtre en sortie

r:addoutputfilter("fooFilter") -- insre le filtre fooFilter dans le flux de sortie</pre>


<pre class="prettyprint lang-lua">r:sendfile(filename) -- envoie un fichier entier au client en utilisant sendfile s'il est
                     -- support par la plateforme :

if use_sendfile_thing then
    r:sendfile("/var/www/large_file.img")
end</pre>


<pre class="prettyprint lang-lua">r:parseargs() -- renvoie deux tables : une table standard de couples
              -- cl/valeur pour les donnes GET simples,
              -- et une autre pour les donnes
              -- multivalues (par exemple foo=1&amp;foo=2&amp;foo=3) :

local GET, GETMULTI = r:parseargs()
r:puts("Votre nom est : " .. GET['name'] or "Unknown")</pre>



<pre class="prettyprint lang-lua">r:parsebody()([sizeLimit]) -- interprte le corps de la
                           -- requte en tant que POST et renvoie
                           -- deux tables lua, comme r:parseargs(). Un
                           -- nombre optionnel peut tre fourni
                           -- pour spcifier le nombre maximal
                           -- d'octets  interprter. La
                           -- valeur par dfaut est 8192.

local POST, POSTMULTI = r:parsebody(1024*1024)
r:puts("Votre nom est : " .. POST['name'] or "Unknown")</pre>



<pre class="prettyprint lang-lua">r:puts("bonjour", " le monde", "!") -- affichage dans le corps de la rponse</pre>


<pre class="prettyprint lang-lua">r:write("une simple chane") -- affichage dans le corps de la rponse</pre>


<pre class="prettyprint lang-lua">r:escape_html("&lt;html&gt;test&lt;/html&gt;") -- Echappe le code HTML et renvoie le rsultat</pre>


<pre class="prettyprint lang-lua">r:base64_encode(string) -- Encode une chane  l'aide du standard de codage Base64.

local encoded = r:base64_encode("This is a test") -- returns VGhpcyBpcyBhIHRlc3Q=</pre>


<pre class="prettyprint lang-lua">r:base64_decode(string) -- Dcode une chane code en Base64.

local decoded = r:base64_decode("VGhpcyBpcyBhIHRlc3Q=") -- returns 'This is a test'</pre>


<pre class="prettyprint lang-lua">r:md5(string) -- Calcule et renvoie le condens MD5 d'une chane en mode binaire (binary safe).

local hash = r:md5("This is a test") -- returns ce114e4501d2f4e2dcea3e17b546f339</pre>


<pre class="prettyprint lang-lua">r:sha1(string) -- Calcule et renvoie le condens SHA1 d'une chane en mode binaire (binary safe).

local hash = r:sha1("This is a test") -- returns a54d88e06612d820bc3be72877c74f257b561b19</pre>


<pre class="prettyprint lang-lua">r:escape(string) -- Echappe une chane de type URL.

local url = "http://foo.bar/1 2 3 &amp; 4 + 5"
local escaped = r:escape(url) -- renvoie 'http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5'</pre>


<pre class="prettyprint lang-lua">r:unescape(string) -- Dschappe une chane de type URL.

local url = "http%3a%2f%2ffoo.bar%2f1+2+3+%26+4+%2b+5"
local unescaped = r:unescape(url) -- renvoie 'http://foo.bar/1 2 3 &amp; 4 + 5'</pre>


<pre class="prettyprint lang-lua">r:construct_url(string) -- Construit une URL  partir d'un URI

local url = r:construct_url(r.uri)</pre>


<pre class="prettyprint lang-lua">r.mpm_query(number) -- Interroge le serveur  propos de son module MPM via la requte ap_mpm_query.

local mpm = r.mpm_query(14)
if mpm == 1 then
    r:puts("Ce serveur utilise le MPM Event")
end</pre>


<pre class="prettyprint lang-lua">r:expr(string) -- Evalue une chane de type <a href="../expr.html">expr</a>.

if r:expr("%{HTTP_HOST} =~ /^www/") then
    r:puts("Ce nom d'hte commence par www")
end</pre>


<pre class="prettyprint lang-lua">r:scoreboard_process(a) -- Interroge le serveur  propos du
                        -- processus  la position <code>a</code>.

local process = r:scoreboard_process(1)
r:puts("Le serveur 1 a comme PID " .. process.pid)</pre>


<pre class="prettyprint lang-lua">r:scoreboard_worker(a, b) -- Interroge le serveur  propos du
                          -- thread <code>b</code>, dans le processus <code>a</code>.

local thread = r:scoreboard_worker(1, 1)
r:puts("L'ID du thread 1 du serveur 1 est " .. thread.tid .. " et son
tat est " .. thread.status)</pre>


<pre class="prettyprint lang-lua">r:clock() -- Renvoie l'heure courante avec une prcision d'une microseconde.</pre>


<pre class="prettyprint lang-lua">r:requestbody(filename) -- Lit et renvoie le corps d'une requte.
                        -- Si 'filename' est spcifi, le
                        -- corps de requte n'est pas
                        -- renvoy, mais sauvegard dans
                        -- le fichier correspondant.

local input = r:requestbody()
r:puts("Vous m'avez envoy le corps de requte suivant :\n")
r:puts(input)</pre>


<pre class="prettyprint lang-lua">r:add_input_filter(filter_name) -- Ajoute le filtre en entre 'filter_name'.</pre>


<pre class="prettyprint lang-lua">r:module_info(module_name) -- Interroge le serveur  propos d'un module.

local mod = r.module_info("mod_lua.c")
if mod then
    for k, v in pairs(mod.commands) do
       r:puts( ("%s: %s\n"):format(k,v)) -- affiche toutes les directives
                                         -- implmentes par ce module.
    end
end</pre>


<pre class="prettyprint lang-lua">r:loaded_modules() -- Renvoie une liste des modules chargs par httpd.

for k, module in pairs(r:loaded_modules()) do
    r:puts("J'ai charg le module " .. module .. "\n")
end</pre>


<pre class="prettyprint lang-lua">r:runtime_dir_relative(filename) -- Gnre le nom d'un fichier run-time
                                 -- (par exemple la mmoire partage
                                 -- "file") relativement au rpertoire de run-time.</pre>


<pre class="prettyprint lang-lua">r:server_info() -- Renvoie une table contenant des informations 
                -- propos du serveur, comme le nom de
                -- l'excutable httpd, le module mpm utilis, etc...</pre>


<pre class="prettyprint lang-lua">r:set_document_root(file_path) -- Dfinit la racine des documents
                               -- pour la requte  file_path.</pre>


<pre class="prettyprint lang-lua">r:add_version_component(component_string) -- Ajoute un lment 
                                          -- la bannire du serveur.</pre>


<pre class="prettyprint lang-lua">r:set_context_info(prefix, docroot) -- Dfinit le prfixe et la
                                    -- racine des documents du contexte pour une requte.</pre>


<pre class="prettyprint lang-lua">r:os_escape_path(file_path) -- Convertit un chemin du systme de
                            -- fichiers en URL indpendamment du systme d'exploitation.</pre>


<pre class="prettyprint lang-lua">r:escape_logitem(string) -- Echappe une chane pour journalisation.</pre>


<pre class="prettyprint lang-lua">r.strcmp_match(string, pattern) -- Vrifie si 'string' correspond 
                                -- 'pattern' via la fonction strcmp_match (GLOBs). Par exemple, est-ce que
                                -- 'www.example.com' correspond  '*.example.com' ?

local match = r.strcmp_match("foobar.com", "foo*.com")
if match then 
    r:puts("foobar.com matches foo*.com")
end</pre>


<pre class="prettyprint lang-lua">r:set_keepalive() -- Dfinit l'tat de persistance d'une requte.
                  -- Renvoie true dans la mesure du possible, false dans le cas contraire.</pre>


<pre class="prettyprint lang-lua">r:make_etag() -- Gnre et renvoie le etag pour la requte courante.</pre>


<pre class="prettyprint lang-lua">r:send_interim_response(clear) -- Renvoie une rponse d'intrim (1xx) au
                               -- client. Si 'clear' est vrai, les en-ttes disponibles
                               -- seront envoys et effacs.</pre>


<pre class="prettyprint lang-lua">r:custom_response(status_code, string) -- Gnre et dfinit une rponse
                                       -- personnalise pour un code d'tat particulier.
                                       -- Le fonctionnement est trs proche de celui de la directive ErrorDocument.

r:custom_response(404, "Baleted!")</pre>


<pre class="prettyprint lang-lua">r.exists_config_define(string) -- Vrifie si une dfinition de configuration existe.

if r.exists_config_define("FOO") then
    r:puts("httpd a probablement t lanc avec l'option -DFOO, ou FOO a
    t dfini dans la configuration")
end</pre>


<pre class="prettyprint lang-lua">r:state_query(string) -- Interroge le serveur  propos de son tat.</pre>


<pre class="prettyprint lang-lua">r:stat(filename [,wanted]) -- Excute stat() sur un fichier, et renvoie une table contenant
                           -- des informations  propos de ce fichier.

local info = r:stat("/var/www/foo.txt")
if info then
    r:puts("Ce fichier existe et a t modifi pour la dernire fois  : " .. info.modified)
end</pre>


<pre class="prettyprint lang-lua">r:regex(string, pattern [,flags]) -- Excute une recherche  base d'expression rationnelle
                                  -- sur une chane, et renvoie les ventuelles correspondances trouves.

local matches = r:regex("foo bar baz", [[foo (\w+) (\S*)]])
if matches then
    r:puts("L'expression rationnelle correspond et le dernier mot
    captur ($2) est : " .. matches[2])
end

-- Exemple avec insensibilit  la casse :
local matches = r:regex("FOO bar BAz", [[(foo) bar]], 1)

-- les drapeaux peuvent tre une combibaison bit  bit de :
-- 0x01: insensibilit  la casse
-- 0x02: recherche multiligne</pre>


<pre class="prettyprint lang-lua">r.usleep(microsecondes) -- Interrompt l'excution du script pendant le nombre de microsecondes spcifi.</pre>


<pre class="prettyprint lang-lua">r:dbacquire(dbType[, dbParams]) -- Acquiert une connexion  une base de donnes et renvoie une classe database.
                                -- Voir '<a href="#databases">Connectivit aux bases de donnes</a>'
				-- pour plus de dtails.</pre>


<pre class="prettyprint lang-lua">r:ivm_set("key", value) -- Dfini une variable Inter-VM avec une valeur spcifique.
                        -- Ces valeurs sont conserves mme si la VM est
			-- arrte ou non utilise, et ne doivent donc tre
			-- utilises que si MaxConnectionsPerChild &gt; 0.
			-- Les valeurs peuvent tre de type number, string
			-- ou boolean et sont stockes sparment pour
			-- chaque processus (elles ne seront donc pas d'une
			-- grande utilit si l'on utilise le mpm prefork).
                        
r:ivm_get("key")        -- Lit le contenu d'une variable dfinie via ivm_set. Renvoie
			-- le contenu de la variable si elle existe, ou nil
			-- dans le cas contraire.
                        
-- Voici un exemple de lecture/criture qui sauvegarde une variable
-- globale en dehors de la VM :
function handle(r)
    -- La premire VM qui effectue l'appel suivant n'obtiendra aucune
    -- valeur, et devra la crer
    local foo = r:ivm_get("cached_data")
    if not foo then
        foo = do_some_calcs() -- simulation de valeurs de retour
        r:ivm_set("cached_data", foo) -- dfinition globale de la variable
    end
    r:puts("La donne en cache est : ", foo)
end</pre>