Commit c66d76bb authored by Nick Kew's avatar Nick Kew
Browse files 

Entering mod_filter and documentation, as previously discussed on dev@httpd.
Please test-drive in time for 2.2.  Currently compatible with 2.0 and up.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@105062 13f79535-47bb-0310-9956-ffa450edef68
parent 3bee5743

docs/manual/images/mod_filter_new.gif

0 → 100644
+3.21 KiB
Loading image diff...

docs/manual/images/mod_filter_old.gif

0 → 100644
+2.07 KiB
Loading image diff...

docs/manual/mod/mod_filter.html

0 → 100644
+3 −0
Original line number Diff line number Diff line 
URI: mod_fiter.html.en

Content-Language: en

Content-type: text/html; charset=ISO-8859-1

docs/manual/mod/mod_filter.html.en

0 → 100644
+387 −0
Original line number Diff line number Diff line 
<?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" xml:lang="en" lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" /><!--

        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

              This file is generated from xml source: DO NOT EDIT

        XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

      -->

<title>mod_filter - Apache HTTP Server</title>

<link title="Main stylesheet" type="text/css" media="all" rel="stylesheet" href="../style/css/manual.css" />

<link title="No Sidebar - Default font size" type="text/css" media="all" rel="alternate stylesheet" href="../style/css/manual-loose-100pc.css" />

<link type="text/css" media="print" rel="stylesheet" href="../style/css/manual-print.css" />

<link rel="shortcut icon" href="../images/favicon.ico" /></head>

<body>

<div id="page-header">

<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>

<p class="apache">Apache HTTP Server Version 2.1</p>

<img src="../images/feather.gif" alt="" /></div>

<div class="up"><a href="./"><img src="../images/left.gif" alt="&lt;-" title="&lt;-" /></a></div>

<div id="path">

<a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.1</a> &gt; <a href="./">Modules</a></div>

<div id="page-content">

<div id="preamble"><h1>Apache Module mod_filter</h1>

<div class="toplang">

<p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English">&nbsp;en&nbsp;</a></p>

</div>

<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Context-sensitive smart filter configuration module</td></tr>

<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>

<tr><th><a href="module-dict.html#ModuleIdentifier">Module Identifier:</a></th><td>filter_module</td></tr>

<tr><th><a href="module-dict.html#SourceFile">Source File:</a></th><td>mod_filter.c</td></tr>

<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Apache 2.0 and higher</td></tr></table>

<h3>Summary</h3>



<p>This module enables smart, context-sensitive configuration of

output content filters.  For example, apache can be configured to

process different content-types through different filters, even

when the content-type is not known in advance (e.g. in a proxy).

</p>

<p>mod_filter works by introducing indirection into the filter

chain.  Instead of inserting filters in the chain, we insert

a filter harness which in turn dispatches conditionally

to a filter provider.  Any content filter may be used as a provider

to mod_filter; no change to existing filter modules is required

(although it may be possible to simplify them).

</p>

</div>

<div id="quickview"><h3 class="directives">Directives</h3>

<ul id="toc">

<li><img src="../images/down.gif" alt="" /> <a href="#filterchain">FilterChain</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#filterdebug">FilterDebug</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#filterdeclare">FilterDeclare</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#filterprotocol">FilterProtocol</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#filterprovider">FilterProvider</a></li>

</ul>

<h3>Topics</h3>

<ul id="topics">

<li><img src="../images/down.gif" alt="" /> <a href="#smart">Smart Filtering</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#terms">Filter Declarations, Providers and Chains</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#config">Configuring the Chain</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#examples">Examples</a></li>

<li><img src="../images/down.gif" alt="" /> <a href="#protocol">Protocol Handling</a></li>

</ul></div>

<div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="section">

<h2><a id="smart" name="smart">Smart Filtering</a></h2>

<p>In the traditional filtering model, filters are inserted unconditionally

using <code class="directive"><a href="../mod/mod_mime.html#addoutputfilter">AddOutputFilter</a></code> and family.

Each filter then needs to determine whether to run, and there is little

flexibility available for server admins to allow the chain to be

configured dynamically.</p>

<p>mod_filter by contrast gives server administrators a great deal of

flexibility in configuring the filter chain.  In fact, filters can be

inserted based on any Request Header, Response Header or Environment

Variable.  This generalises the limited flexibility offered by

<code class="directive"><a href="../mod/core.html#addoutputfilterbytype">AddOutputFilterByType</a></code>, and fixes

it to work correctly with dynamic content, regardless of the

content generator.  The ability to dispatch based on Environment

Variables offers the full flexibility of configuration with

<code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to anyone who needs it.</p>



</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="section">

<h2><a id="terms" name="terms">Filter Declarations, Providers and Chains</a></h2>

<img src="../images/mod_filter_old.gif" alt="" />

<p>In the traditional model, output filters are a simple chain

from the content generator (handler) to the client.  This works well

provided the filter chain can be correctly configured, but presents

problems when the filters need to be configured dynamically based on

the outcome of the handler.</p>

<img src="../images/mod_filter_new.gif" alt="" />

<p>mod_filter works by introducing indirection into the filter

chain.  Instead of inserting filters in the chain, we insert

a filter harness which in turn dispatches conditionally

to a filter provider.  Any content filter may be used as a provider

to mod_filter; no change to existing filter modules is required

(although it may be possible to simplify them).  There can be

multiple providers for one filter, but no more than one provider will

run for any single request.

</p>

<p>A filter chain comprises any number of instances of the filter

harness, each of which may have any number of providers.  A special

case is that of a single provider with unconditional dispatch: this

is equivalent to inserting the provider filter directly into the chain.

</p>

</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="section">

<h2><a id="config" name="config">Configuring the Chain</a></h2>

<p>There are three stages to configuring a filter chain with mod_filter.

For details of the directives, see below.</p>

<dl>

<dt>Declare Filters</dt>

<dd>The <code class="directive">FilterDeclare</code> directive declares a filter,

assigning it a name and a dispatch criterion.</dd>

<dt>Register Providers</dt>

<dd>The <code class="directive">FilterProvider</code> directive registers a provider with a filter.

The filter must have been registered with <code class="directive">FilterDeclare</code>.

The provider must have been registered with

<code>ap_register_output_filter</code> by some module.  The final argument

to <code class="directive">FilterProvider</code> is a match string, that will be checked against

the filter's dispatch criterion to determine whether to run this provider.</dd>

<dt>Configure the Chain</dt>

<dd>The above directives build components of a smart filter chain,

but do not configure it to run.  The <code class="directive">FilterChain</code> directive

builds a filter chain from smart filters declared, offering the

flexibility to insert filters at the beginning or end of the chain,

remove a filter, or clear the chain.</dd>

</dl>

</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="section">

<h2><a id="examples" name="examples">Examples</a></h2>

<dl>

<dt>Serverside Includes (SSI)</dt>

<dd>

<p>A simple case of using mod_filter in place of

<code>AddOutputFilterByType</code></p>

<div class="example"><p><code>

FilterDeclare SSI Content-Type<br />

FilterProvider SSI INCLUDES $text/html<br />

FilterChain SSI<br />

</code></p></div>

</dd>

<dt>Serverside Includes (SSI)</dt>

<dd>

<p>The same as the above but dispatching on handler (classic

SSI behaviour; .shtml files get processed).</p>

<div class="example"><p><code>

FilterDeclare SSI Handler<br />

FilterProvider SSI INCLUDES server-parsed<br />

FilterChain SSI<br />

</code></p></div>

</dd>

<dt>Emulating mod_gzip with mod_deflate</dt>

<dd>

<p>Insert INFLATE filter only if "gzip" is NOT in the

Accept-Encoding header.</p>

<div class="example"><p><code>

FilterDeclare gzip req=Accept-Encoding<br />

FilterProvider gzip inflate !$gzip<br />

FilterChain gzip<br />

</code></p></div>

</dd>

<dt>Image Downsampling</dt>

<dd>

<p>Suppose we want to downsample all web images, and have filters

for GIF, JPEG and PNG.</p>

<div class="example"><p><code>

FilterDeclare unpack Content-Type<br />

FilterProvider unpack jpeg_unpack $image/jpeg<br />

FilterProvider unpack gif_unpack $image/gif<br />

FilterProvider unpack png_unpack $image/png<br />

FilterDeclare downsample Content-Type<br />

FilterProvider downsample downsample_filter $image<br />

FilterProtocol downsample "change=yes"<br />

FilterDeclare repack Content-Type<br />

FilterProvider repack jpeg_pack $image/jpeg<br />

FilterProvider repack gif_pack $image/gif<br />

FilterProvider repack png_pack $image/png<br />

&lt;Location /image-filter&gt;<br />

FilterChain unpack downsample repack<br />

&lt;/Location&gt;

</code></p></div>

</dd>

</dl>

</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="section">

<h2><a id="protocol" name="protocol">Protocol Handling</a></h2>

<p>Historically, each filter is responsible for ensuring that whatever

changes it makes are correctly represented in the HTTP response headers,

and that it does not run when it would make an illegal change.  This

imposes a burden on filter authors to re-implement some common

functionality in every filter:</p>

<ul>

<li>Many filters will change the content, invalidating existing content

tags, checksums, hashes, and lengths.</li>

<li>Filters that require an entire, unbroken response in input need to

ensure they don't get byteranges from a backend.</li>

<li>Filters that transform output in a filter need to ensure they don't

violate a <code>Cache-Control: no-transform</code> header from the

backend.</li>

<li>Filters may make responses uncacheable.</li>

</ul>

<p>mod_filter aims to offer generic handling of these details of filter

implementation, reducing the complexity required of content filter modules.

This is work-in-progress; the <code class="directive">FilterProtocol</code>

implements some of this functionality, but there are no API calls yet.</p>

<p>At the same time, mod_filter should not interfere with a filter that

wants to handle all aspects of the protocol.  By default (i.e. in the

absence of any <code class="directive">FilterProtocol</code> directives), mod_filter

will leave the headers untouched.</p>

</div>

<div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="directive-section"><h2><a id="FilterChain" name="FilterChain">FilterChain</a> <a id="filterchain" name="filterchain">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Configure the filter chain</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterChain ([+=-@!]<var>filter-name</var>)+</code></td></tr>

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

</table>

<p>This configures an actual filter chain, from declared filters.

<code class="directive">FilterChain</code> takes any number of arguments,

each optionally preceded with a single-character control that

determines what to do:</p>

<dl>

<dt>+filter-name</dt>

<dd>Add filter-name to the end of the filter chain</dd>

<dt>@filter-name</dt>

<dd>Insert filter-name at the start of the filter chain</dd>

<dt>-filter-name</dt>

<dd>Remove filter-name from the filter chain</dd>

<dt>=filter-name</dt>

<dd>Empty the filter chain and insert filter-name</dd>

<dt>!</dt>

<dd>Empty the filter chain</dd>

<dt>filter-name</dt>

<dd>Equivalent to +filter-name</dd>

</dl>



</div>

<div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="directive-section"><h2><a id="FilterDebug" name="FilterDebug">FilterDebug</a> <a id="filterdebug" name="filterdebug">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Get debug/diagnostic information from mod_filter</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDebug filter-name level</code></td></tr>

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

</table>

<p>This directive generates debug information from mod_filter.

It is designed to help test and debug providers (filter modules), although

it may also help with mod_filter itself.</p>

<p>The debug output depends on the level set:</p>

<dl>

<dt>0 (default)</dt>

<dd>No debug information is generated.</dd>

<dt>1</dt>

<dd>mod_filter will record buckets and brigades passing through the filter

to the error log, before the provider has processed them.

This is similar to the information generated by

<a href="http://apache.webthing.com/mod_diagnostics/">mod_diagnostics</a>.

</dd>

<dt>2 (not yet implemented)</dt>

<dd>Will dump the full data passing through to a tempfile before the provider.

<strong>For single-user debug only</strong>; this will not

support concurrent hits.</dd>

</dl>



</div>

<div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="directive-section"><h2><a id="FilterDeclare" name="FilterDeclare">FilterDeclare</a> <a id="filterdeclare" name="filterdeclare">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Declare a smart filter</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterDeclare <var>filter-name</var> [req|resp|env]=<var>dispatch</var>

<var>[type]</var>

</code></td></tr>

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

</table>

<p>This directive declares an output filter together with a

header or environment variable that will determine runtime

configuration.  The first argument is a <code>filter-name</code>

for use in <code class="directive">FilterProvider</code>,

<code class="directive">FilterChain</code> and

<code class="directive">FilterProtocol</code> directives.</p>

<p>The second is a string with optional <code>req=</code>,

<code>resp=</code> or <code>env=</code> prefix causing it

to dispatch on (respectively) the request header, response

header, or environment variable named.  In the absence of a

prefix, it defaults to a response header.  A special case is the

word "handler", which causes mod_filter to dispatch on the handler.</p>

<p>The final (optional) argument

is the type of filter, and takes values of <var>ap_filter_type</var>

- namely <var>RESOURCE</var> (the default), <var>CONTENT_SET</var>,

<var>PROTOCOL</var>, <var>TRANSCODE</var>, <var>CONNECTION</var>

or <var>NETWORK</var>.

</p>





</div>

<div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="directive-section"><h2><a id="FilterProtocol" name="FilterProtocol">FilterProtocol</a> <a id="filterprotocol" name="filterprotocol">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Deal with correct HTTP protocol handling</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProtocol filter-name [provider-name] "proto-flags"</code></td></tr>

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

</table>

<p>This directs mod_filter to deal with ensuring the filter doesn't run

when it shouldn't, and that the HTTP response headers are correctly set

taking into account the effects of the filter.</p>

<p>There are two forms of this directive.  With three arguments, it

applies specifically to a filter-name and a provider for that filter.

With two arguments it applies to a filter-name whenever the filter runs

<em>any</em> provider.</p>

<p>proto-flags is one or more of</p>

<dl>

<dt>change=yes</dt>

<dd>The filter changes the content, including possibly the content length</dd>

<dt>change=1:1</dt>

<dd>The filter changes the content, but will not change the content length</dd>

<dt>byteranges=no</dt>

<dd>The filter cannot work on byteranges and requires complete input</dd>

<dt>proxy=no</dt>

<dd>The filter should not run in a proxy context</dd>

<dt>proxy=transform</dt>

<dd>The filter transforms the response in a manner incompatible with

the HTTP <code>Cache-Control: no-transform</code> header.</dd>

<dt>cache=no</dt>

<dd>The filter renders the output uncacheable (eg by introducing randomised

content changes)</dd>

</dl>



</div>

<div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div>

<div class="directive-section"><h2><a id="FilterProvider" name="FilterProvider">FilterProvider</a> <a id="filterprovider" name="filterprovider">Directive</a></h2>

<table class="directive">

<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Register a content filter</td></tr>

<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>FilterProvider <var>filter-name</var> <var>provider-name</var> <var>match</var></code></td></tr>

<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>

<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>

<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_filter</td></tr>

</table>

<p>This directive registers a <em>provider</em> for the smart filter.

The provider will be called if and only if the <var>match</var> declared

here matches the value of the header or environment variable declared

as <var>dispatch</var> in the <code class="directive">FilterDeclare</code>

directive that declared <var>filter-name</var>.</p>

<p><var>filter-name</var> must have been declared with 

<code class="directive">FilterDeclare</code>.  <var>provider-name</var> must have

been registered by loading a module that registers the name with

<code>ap_register_output_filter</code>.</p>

<p>The <var>match</var> argument specifies a match that will be applied to

the filter's <var>dispatch</var> criterion.  The match may be a string

match (exact match or substring), a regexp, an integer (greater, lessthan

or equals), or unconditional.  The first characters of the <var>match</var>

argument determines this:</p>

<p><strong>First</strong>, if the first character is an exclamation mark

<strong>!</strong>, this reverses the rule, so the provider will be used

if and only if the match <em>fails</em>.</p>

<p><strong>Second</strong>, it interprets the first character excluding

any leading ! as follows:</p>

<dl>

<dt>default</dt>

<dd>exact match</dd>

<dt>$</dt>

<dd>substring match</dd>

<dt>/</dt>

<dd>regexp match</dd>

<dt>=</dt>

<dd>integer equality</dd>

<dt>&lt;</dt>

<dd>integer less-than</dd>

<dt>&gt;</dt>

<dd>integer greater-than</dd>

<dt>*</dt>

<dd>Unconditional match</dd>

</dl>



</div>

</div>

<div class="bottomlang">

<p><span>Available Languages: </span><a href="../en/mod/mod_filter.html" title="English">&nbsp;en&nbsp;</a></p>

</div><div id="footer">

<p class="apache">Copyright 1999-2004 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>

<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>

</body></html>

docs/manual/mod/mod_filter.xml

0 → 100644
+361 −0

File added.

Preview size limit exceeded, changes collapsed.