From: Eric Covener Date: Sat, 21 Apr 2018 15:43:20 +0000 (+0000) Subject: xforms for mod_filter X-Git-Tag: 2.5.0-alpha2-ci-test-only~2665 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6ca32f9eb40935231fe20e794ca66ba95af089de;p=thirdparty%2Fapache%2Fhttpd.git xforms for mod_filter git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1829714 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_filter.html.en b/docs/manual/mod/mod_filter.html.en index 155d97a1fcc..7c06932f139 100644 --- a/docs/manual/mod/mod_filter.html.en +++ b/docs/manual/mod/mod_filter.html.en @@ -70,7 +70,7 @@
  • Comments
    • top
    -

    Smart Filtering

    +

    Smart Filtering

    In the traditional filtering model, filters are inserted unconditionally using AddOutputFilter and family. Each filter then needs to determine whether to run, and there is little @@ -84,7 +84,7 @@ flexibility offered by AddOutputFilterByType.

    top
    -

    Filter Declarations, Providers and Chains

    +

    Filter Declarations, Providers and Chains

    [This image displays the traditional filter model]
    Figure 1: The traditional filter model

    @@ -114,22 +114,20 @@ is equivalent to inserting the provider filter directly into the chain.

    top
    -

    Configuring the Chain

    +

    Configuring the Chain

    There are three stages to configuring a filter chain with mod_filter. For details of the directives, see below.

    Declare Filters
    The FilterDeclare directive - declares a filter, assigning it a name and filter type. Required - only if the filter is not the default type AP_FTYPE_RESOURCE.
    - + declares a new smart filter, assigning it a name and optional filter + type.
    Register Providers
    The FilterProvider directive registers a provider with a filter. The filter may have been declared with FilterDeclare; if not, FilterProvider will implicitly - declare it with the default type AP_FTYPE_RESOURCE. The provider - must have been + declare it. The provider must have been registered with ap_register_output_filter by some module. The final argument to FilterProvider is an expression: the provider will be selected to run for a request if and only if the expression evaluates @@ -148,7 +146,7 @@
    top
    -

    Filtering and Response Status

    +

    Filtering and Response Status

    mod_filter normally only runs filters on responses with HTTP status 200 (OK). If you want to filter documents with other response statuses, you can set the filter-errordocs @@ -157,7 +155,7 @@ expression conditions with FilterProvider.

    top
    -

    Upgrading from Apache HTTP Server 2.2 Configuration

    +

    Upgrading from Apache HTTP Server 2.2 Configuration

    The FilterProvider directive has changed from httpd 2.2: the match and dispatch arguments are replaced with a single but @@ -174,10 +172,12 @@ replaced by regular expression matches.

    top
    -

    Examples

    +

    Examples

    Server side Includes (SSI)
    -
    A simple case of replacing AddOutputFilterByType +
    A simple case replacing AddOutputFilterByType. + This example creates a new smart filter named "SSI" that conditionally leverates + the "INCLUDES" filter from mod_include as a provider. 
    FilterDeclare SSI
 FilterProvider SSI INCLUDES "%{CONTENT_TYPE} =~ m|^text/html|"
 FilterChain SSI
    @@ -193,17 +193,24 @@ FilterChain SSI
    Emulating mod_gzip with mod_deflate
    -
    Insert INFLATE filter only if "gzip" is NOT in the - Accept-Encoding header. This filter runs with ftype CONTENT_SET. +
    This example demonstrates the dynamic properties granted to traditional + filters when a smart filter is constructed around them. A new smart filter + named "gzip" is created that dynamically inserts mod_deflate's + INFLATE filter only if "gzip" is NOT in the Accept-Encoding header. + The gzip smart filter runs with type CONTENT_SET. 
    FilterDeclare gzip CONTENT_SET
-FilterProvider gzip inflate "%{req:Accept-Encoding} !~ /gzip/"
+FilterProvider gzip INFLATE "%{req:Accept-Encoding} !~ /gzip/"
 FilterChain gzip
    Image Downsampling
    -
    Suppose we want to downsample all web images, and have filters - for GIF, JPEG and PNG. +
    This example demonstrates further abstractions that the smart filtering. + Suppose we want to downsample all web images, and have different + filter providers for manipulating GIF, JPEG and PNG + The configuration defines smart filters "unpack" and "repack" via + the harness that invokes the right underlying filter providers based on + the content type at runtime. 
    FilterProvider unpack jpeg_unpack "%{CONTENT_TYPE} = 'image/jpeg'"
 FilterProvider unpack gif_unpack  "%{CONTENT_TYPE} = 'image/gif'"
 FilterProvider unpack png_unpack  "%{CONTENT_TYPE} = 'image/png'"
@@ -222,7 +229,7 @@ FilterProvider repack png_pack  "%{CONTENT_TYPE} = 'image/png'"
    top
    -

    Protocol Handling

    +

    Protocol Handling

    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 @@ -263,7 +270,7 @@ FilterProvider repack png_pack "%{CONTENT_TYPE} = 'image/png'" Modules using it should test it carefully.

    top
    -

    AddOutputFilterByType Directive

    +

    AddOutputFilterByType Directive

    Description:assigns an output filter to a particular media-type
    Syntax:AddOutputFilterByType filter[;filter...] @@ -312,10 +319,10 @@ being moved to mod_filter<
    top
    -

    FilterChain Directive

    +

    FilterChain Directive

    - + @@ -327,31 +334,31 @@ being moved to mod_filter< determines what to do:

    -
    +filter-name
    +
    +smart-filter-name
    Add filter-name to the end of the filter chain
    -
    @filter-name
    -
    Insert filter-name at the start of the filter chain
    +
    @smart-filter-name
    +
    Insert smart-filter-name at the start of the filter chain
    -
    -filter-name
    -
    Remove filter-name from the filter chain
    +
    -smart-filter-name
    +
    Remove smart-filter-name from the filter chain
    -
    =filter-name
    -
    Empty the filter chain and insert filter-name
    +
    =smart-filter-name
    +
    Empty the filter chain and insert smart-filter-name
    !
    Empty the filter chain
    -
    filter-name
    -
    Equivalent to +filter-name
    +
    smart-filter-name
    +
    Equivalent to +smart-filter-name
    top
    -

    FilterDeclare Directive

    +

    FilterDeclare Directive

    Description:Configure the filter chain
    Syntax:FilterChain [+=-@!]filter-name ...
    Syntax:FilterChain [+=-@!]smart-filter-name ...
    Context:server config, virtual host, directory, .htaccess
    Override:Options
    Status:Base
    - + @@ -359,7 +366,7 @@ being moved to mod_filter<
    Description:Declare a smart filter
    Syntax:FilterDeclare filter-name [type]
    Syntax:FilterDeclare smart-filter-name [type]
    Context:server config, virtual host, directory, .htaccess
    Override:Options
    Status:Base

    This directive declares an output filter together with a header or environment variable that will determine runtime - configuration. The first argument is a filter-name + configuration. The first argument is a smart-filter-name for use in FilterProvider, FilterChain and FilterProtocol directives.

    @@ -372,10 +379,10 @@ being moved to mod_filter<
    top
    -

    FilterProtocol Directive

    +

    FilterProtocol Directive

    - @@ -388,9 +395,9 @@ being moved to mod_filter< filter.

    There are two forms of this directive. With three arguments, it - applies specifically to a filter-name and a + applies specifically to a smart-filter-name and a provider-name for that filter. - With two arguments it applies to a filter-name whenever the + With two arguments it applies to a smart-filter-name whenever the filter runs any provider.

    Flags specified with this directive are merged with the flags @@ -428,10 +435,10 @@ being moved to mod_filter<

    top
    -

    FilterProvider Directive

    +

    FilterProvider Directive

    Description:Deal with correct HTTP protocol handling
    Syntax:FilterProtocol filter-name [provider-name] +
    Syntax:FilterProtocol smart-filter-name [provider-name] proto-flags
    Context:server config, virtual host, directory, .htaccess
    Override:Options
    - @@ -460,11 +467,11 @@ for a complete reference and examples.
    top
    -

    FilterTrace Directive

    +

    FilterTrace Directive

    Description:Register a content filter
    Syntax:FilterProvider filter-name provider-name +
    Syntax:FilterProvider smart-filter-name provider-name expression
    Context:server config, virtual host, directory, .htaccess
    Override:Options
    - +
    Description:Get debug/diagnostic information from mod_filter
    Syntax:FilterTrace filter-name level
    Syntax:FilterTrace smart-filter-name level
    Context:server config, virtual host, directory
    Status:Base
    Module:mod_filter