Module Apache mod_filter

Filtrage intelligent

Dans le mod�le de filtrage traditionnel, les filtres sont ins�r�s sans condition � l'aide de la directive AddOutputFilter et des directives apparent�es. Chaque filtre doit ensuite d�terminer s'il doit s'ex�cuter ou non, et les administrateurs du serveur disposent de peu de souplesse pour faire en sorte que la cha�ne soit trait�e de mani�re dynamique.

mod_filter, � l'oppos�, fournit aux administrateurs du serveur un grand degr� de souplesse pour configurer la cha�ne de filtrage. Concr�tement, la d�cision d'ins�rer un filtre peut �tre prise en fonction d'une expression bool�enne complexe. Ceci g�n�ralise le fonctionnement relativement souple de la directive AddOutputFilterByType.

D�clarations de filtres, fournisseurs et cha�nes

Figure 1: Le mod�le de filtrage traditionnel

Dans le mod�le traditionnel, les filtres en sortie constituent une simple cha�ne s'�tendant depuis le g�n�rateur de contenu (ou gestionnaire) jusqu'au client. Ce fonctionnement peut convenir s'il permet d'atteindre le but recherch�, mais pose probl�me lorsque cette cha�ne doit �tre configur�e dynamiquement en fonction de la sortie du gestionnaire.

Figure 2: Le mod�le de fonctionnement de mod_filter

Le fonctionnement de mod_filter consiste � introduire des branchements dans la cha�ne de filtrage. Plut�t que d'ins�rer directement des filtres dans la cha�ne, on ins�re un s�lecteur de filtre qui va effectuer un branchement conditionnel vers un fournisseur de filtre. mod_filter peut utiliser tout filtre de contenu comme fournisseur ; aucune modification des modules de filtrage existants n'est n�cessaire (bien qu'il soit tout de m�me possible de les simplifier). Il peut y avoir plusieurs fournisseurs pour un seul filtre, mais un seul fournisseur sera choisi pour chaque requ�te.

Une cha�ne de filtrage peut comporter autant d'instances du s�lecteur de filtre que l'on souhaite, chacune d'entre elles pouvant disposer de plusieurs fournisseurs. Un s�lecteur de filtre poss�dant un seul fournisseur dont le choix est inconditionnel constitue un cas particulier : cette situation est �quivalente � l'insertion directe du filtre dans la cha�ne.

Configuration de la cha�ne de filtrage

Trois �tapes sont n�cessaires pour configurer une cha�ne de filtrage avec mod_filter. Voir ci-dessous la description d�taill�e des directives.

D�claration des filtres

La directive FilterDeclare permet de d�clarer un filtre en lui assignant un nom et un type. Elle n'est obligatoire que si le filtre n'est pas du type par d�faut AP_FTYPE_RESOURCE.

Enregistrement des fournisseurs

La directive FilterProvider permet d'associer un fournisseur � un filtre. Le filtre a �t� �ventuellement d�clar� � l'aide de la directive FilterDeclare ; si ce n'est pas le cas, FilterProvider va le d�clarer implicitement avec le type par d�faut AP_FTYPE_RESOURCE. Le fournisseur doit avoir �t� enregistr� � l'aide de ap_register_output_filter par un module quelconque. Le dernier argument de la directive FilterProvider est une expression : le fournisseur s'ex�cutera pour une requ�te si et seulement si l'expression est �valu�e vraie. L'expression peut �valuer une requ�te HTTP ou les en-t�tes de la r�ponse, des variables d'environnement, ou le gestionnaire utilis� par cette requ�te. � la diff�rence des version pr�c�dentes, mod_filter supporte d�sormais les expressions complexes associant des crit�res multiples au moyen d'une logique AND / OR (&& / ||) et de parenth�ses. Pour les d�tails sur la syntaxe de l'expression, voir la documentation sur ap_expr.

Configuration de la cha�ne de filtrage

Les directives ci-dessus permettent d'�laborer les �l�ments d'une cha�ne de filtrage intelligente, mais pas de les configurer en vue de leur ex�cution. La directive FilterChain �labore une cha�ne de filtrage � partir de filtres intelligents d�clar�s, permettant avec souplesse d'ins�rer des filtres au d�but ou � la fin de la cha�ne, de supprimer un filtre ou m�me la cha�ne compl�te.

Filtrage et statut de la r�ponse

Normalement, mod_filter n'applique les filtres qu'aux r�ponses poss�dant un statut HTTP 200 (OK). Pour pouvoir filtrer des documents poss�dant un autre statut, vous devez d�finir la variable d'environnement filter-errordocs, les r�ponses �tant alors filtr�es sans se pr�occuper de leur statut. Pour d�finir ce comportement de mani�re plus fine, vous pouvez utiliser des conditions dans la directive FilterProvider.

Mise � jour depuis une configuration du serveur HTTP Apache 2.2

La directive FilterProvider a �t� modifi�e par rapport � httpd 2.2 : les arguments match et dispatch ont �t� remplac�s par l'argument unique expression plus polyvalent. En g�n�ral, il est possible de convertir une paire match/dispatch vers les deux c�t�s d'une expression, de la mani�re suivante :

Les en-t�tes de requ�te et de r�ponse et les variables d'environnement sont maintenant interpr�t�s selon les syntaxes respectives %{req:foo}, %{resp:foo} et %{env:foo}. Les variables %{HANDLER} et %{CONTENT_TYPE} sont �galement support�es.

Notez que l'�valuation de l'expression ne supporte plus les comparaisons de sous-cha�nes. Ces derni�res peuvent �tre remplac�es par des comparaisons d'expressions rationnelles.

Exemples

Inclusions c�t� serveur (SSI)

Un exemple simple de remplacement de la directive AddOutputFilterByType

FilterDeclare SSI
FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
FilterChain SSI

Inclusions c�t� serveur (SSI)

M�me exemple que ci-dessus, mais envoi vers un gestionnaire (comportement classique des SSI ; les fichiers .shtml sont trait�s).

FilterProvider SSI INCLUDES "%{HANDLER} = 'server-parsed'"
FilterChain SSI

�mulation de mod_gzip avec mod_deflate

Insertion du filtre INFLATE seulement si l'en-t�te Accept-Encoding a une valeur autre que "gzip". Ce filtre s'ex�cute avec le type ftype CONTENT_SET.

FilterDeclare gzip CONTENT_SET
FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
FilterChain gzip

Diminution de la r�solution d'une image

Supposons que nous voulions r�duire la r�solution de toutes les images web, et que nous disposions de filtres pour les images GIF, JPEG et PNG.

FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider unpack gif_unpack "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider unpack png_unpack "%{CONTENT_TYPE} = 'image/png'"

FilterProvider downsample downsample_filter "%{CONTENT_TYPE} = m|^image/(jpeg|gif|png)|"
FilterProtocol downsample "change=yes"

FilterProvider repack jpeg_pack "%{CONTENT_TYPE} = 'image/jpeg'"
FilterProvider repack gif_pack "%{CONTENT_TYPE} = 'image/gif'"
FilterProvider repack png_pack "%{CONTENT_TYPE} = 'image/png'"
<Location /image-filter>
    FilterChain unpack downsample repack
</Location>

Gestion de protocole

Historiquement, tout filtre doit s'assurer que toute modification qu'il effectue est correctement repr�sent�e dans les en-t�tes de la r�ponse HTTP, et qu'il ne s'ex�cutera pas si cette ex�cution r�sultait en une modification interdite. Ceci impose aux auteurs de filtres la corv�e de r�impl�menter certaines fonctionnalit�s communes dans chaque filtre :

• De nombreux filtres modifient les contenus, et de ce fait invalident les balises de ces contenus, leur somme de contr�le, leur condens� (hash) existant, ainsi que leur taille.
• Les filtres qui n�cessitent une r�ponse enti�re et non tronqu�e en entr�e, doivent s'assurer qu'il n'ont pas re�u une r�ponse � une requ�te partielle.
• Les filtres qui modifient la sortie d'un autre filtre doivent s'assurer qu'ils ne violent pas la directive d'un en-t�te Cache-Control: no-transform �ventuel.
• Les filtres peuvent agir sur des r�ponses de fa�on � ce qu'elles ne puissent plus �tre mises en cache.

mod_filter a pour but de g�rer de mani�re g�n�rale ces d�tails de l'impl�mentation des filtres, r�duisant par l�-m�me la complexit� des modules de filtrage de contenu. Le travail permettant d'atteindre ce but est cependant toujours en cours ; la directive FilterProtocol impl�mente certaines de ces fonctionnalit�s � des fins de compatibilit� ascendante avec les modules d'Apache 2.0. Pour les versions 2.1 et sup�rieures de httpd, les API ap_register_output_filter_protocol et ap_filter_protocol permettent aux modules de filtrage de d�finir leurs propres comportements.

Cependant, mod_filter ne doit pas interf�rer avec un filtre qui g�re d�j� tous les aspects du protocole. Par d�faut (c'est � dire en l'absence de toute directive FilterProtocol), mod_filter ne modifiera donc pas les en-t�tes.

Au moment o� ces lignes sont �crites, cette fonctionnalit� a �t� tr�s peu test�e, car les modules d'usage courant ont �t� con�us pour fonctionner avec httpd 2.0. Les modules qui l'utilisent devront donc l'exp�rimenter avec pr�cautions.