mod_filter

摘要

此模块支持智能，context-sensitive 配置输出内容过滤器。对于 example，apache 可以配置为通过不同的过滤器处理不同的 content-types，即使事先不知道 content-type(代理中的 e.g.)也是如此。

mod_filter通过将间接引入过滤器链来工作。我们不是在链中插入过滤器，而是插入过滤器线束，然后过滤器线束有条件地分配给过滤器提供者。任何内容过滤器都可以用作mod_filter的提供者；不需要更改现有的过滤器模块(尽管可以简化它们)。

智能过滤

在传统的过滤 model 中，使用AddOutputFilter和 family 无条件地插入过滤器。然后，每个过滤器都需要确定是否 run，并且服务器管理员几乎没有灵活性允许动态配置链。

相比之下，mod_filter使服务器管理员在配置过滤器链时具有很大的灵活性。事实上，可以根据复杂的_bo 插入过滤器。这概括了AddOutputFilterByType提供的有限灵活性。

过滤器声明，提供者和链

图 1：传统的过滤器 model

在传统的 model 中，输出过滤器是从内容 generator(处理程序)到 client 的简单链。如果可以正确配置过滤器链，这很有效，但是当需要根据处理程序的结果动态配置过滤器时会出现问题。

图 2：mod_filter model

mod_filter通过将间接引入过滤器链来工作。我们不是在链中插入过滤器，而是插入过滤器线束，然后过滤器线束有条件地分配给过滤器提供者。任何内容过滤器都可以用作mod_filter的提供者；不需要更改现有的过滤器模块(尽管可以简化它们)。一个过滤器可以有多个提供程序，但对于任何单个请求，只能运行一个提供程序。

过滤器链包括过滤器线束的任何数量的实例，每个实例可具有任何数量的提供者。一个特殊情况是具有无条件分派的单个提供者：这相当于将提供者过滤器直接插入链中。

配置链

使用mod_filter配置过滤器链有三个阶段。有关指令的详细信息，请参阅下文。

• 声明过滤器
  FilterDeclare 指令声明一个过滤器，为其指定一个 name 和过滤器类型。仅在筛选器不是默认类型 AP_FTYPE_RESOURCE 时才需要。
• 注册提供商
  FilterProvider 指令向提供程序注册过滤器。过滤器可能已使用 FilterDeclare 声明；如果没有，FilterProvider 将使用默认类型 AP_FTYPE_RESOURCE 隐式声明它。提供者必须已通过某个模块注册 ap_register_output_filter。 FilterProvider 的最后一个参数是一个表达式：当且仅当表达式的计算结果为 true 时，才会选择提供程序来运行请求。表达式可以评估 HTTP 请求或响应 headers，环境变量或此请求使用的 Handler。与早期版本不同，mod_filter 现在支持涉及带 AND/OR 逻辑(&&/||)和括号的多个条件的复杂表达式。表达式语法的详细信息在 ap_expr 文档中描述。
• 配置链
  以上指令 build 智能过滤器链的组件，但不要将其配置为 run。 FilterChain 指令根据声明的智能过滤器构建过滤器链，提供在链的开头或末尾插入过滤器，删除过滤器或清除链的灵活性。

过滤和响应状态

mod_filter 通常仅在 HTTP 状态为 200(OK)的响应上运行过滤器。如果要过滤具有其他响应状态的文档，可以设置 filter-errordocs 环境变量，它将适用于所有响应，无论状态如何。要进一步细化，可以将表达式条件与FilterProvider一起使用。

从 Apache HTTP Server 2.2 Configuration 升级

FilterProvider指令已从 httpd 2.2 更改：match 和 dispatch arguments 被替换为单个但更通用的表达式。通常，您可以使用以下内容将 match/dispatch 对转换为表达式的两边：

"dispatch ='match'"

现在，从语法％{解释 Request headers，Response headers 和 Environment 变量。 40}，％{。 41}和％{。分别为 42。变量％{。 43}和％{。 44}也受支持。

请注意，match 不再支持子字符串匹配。它们可以用正则表达式匹配替换。

例子

• 服务器端包含(SSI)
  替换 AddOutputFilterByType FilterDeclare SSI 的简单情况
  FilterProvider SSI 包含“％{。45}=~m |^ text/html |”
  FilterChain SSI
• 服务器端包含(SSI)
  与上面相同但是在处理程序上调度(经典的 SSI 行为;.shtml files 得到处理)。 FilterProvider SSI 包含“％{。46}='server-parsed'”
  FilterChain SSI
• 用 mod_deflate 模拟 mod_gzip
  仅当“gzip”不在 Accept-Encoding 标题中时，才插入 INFLATE 过滤器。此过滤器使用 ftype CONTENT_SET 运行。 FilterDeclare gzip CONTENT_SET
  FilterProvider gzip inflate“％{。47}！~/gzip/”
  FilterChain gzip
• 图像下采样
  假设我们要对所有 web 图像进行下采样，并为 GIF，JPEG 和 PNG 设置过滤器。 FilterProvider unpack jpeg_unpack“％{。48}='image/jpeg'”
  FilterProvider 解包 gif_unpack“％{。49}='image/gif'”
  FilterProvider 解包 png_unpack“％{。50}='image/png'”

FilterProvider 下采样 downsample_filter“％{。51}= m |^ image/(jpeg | gif | png)|”
FilterProtocol 下采样“change=yes”

FilterProvider 重新包装 jpeg_pack“％{。52}='image/jpeg'”
FilterProvider 重新包装 gif_pack“％{。53}='image/gif'”
FilterProvider 重新包装 png_pack“％{。54}='image/png'”
<Location "7">
FilterChain 解压缩下采样重新包装
</Location>

协议处理

从历史上看，每个过滤器都负责确保它所做的任何更改都在 HTTP 响应 headers 中正确表示，并且当它进行非法更改时它不会运行。这会给过滤器作者带来负担，使每个过滤器都有 re-implement 一些 common 功能：

• 许多过滤器都会更改内容，使现有内容标记，校验和，哈希值和长度无效。
• 需要在输入中进行完整，不间断响应的过滤器需要确保它们不会从后端获得字节范围。
• 转换过滤器中输出的过滤器需要确保它们不会违反后端的Cache-Control: no-transform标头。
• 过滤器可能会使响应无法缓存。

mod_filter旨在提供对 filter implementation 的这些细节的通用处理，从而降低内容过滤器模块所需的复杂性。这是 work-in-progress;FilterProtocol使用 Apache 2.0 模块为 back-compatibility 实现了一些此功能。对于 httpd 2.1 和更高版本，ap_register_output_filter_protocol和ap_filter_protocol API 使过滤器模块能够声明自己的行为。

在同一时间，mod_filter不应干扰想要处理协议所有方面的过滤器。默认情况下(i.e.在没有任何FilterProtocol指令的情况下)，mod_filter将保持 headers 不受影响。

在撰写本文时，这个 feature 很大程度上未经测试，因为 common 使用的模块设计用于 2.0.使用它的模块应该仔细测试。

AddOutputFilterByType 指令

该指令根据响应media-type激活请求的特定输出过滤。

以下 example 使用DEFLATE过滤器，该过滤器由mod_deflate提供。它将压缩所有输出(静态或动态)，在将其发送到 client 之前标记为text/html或text/plain。

AddOutputFilterByType DEFLATE text/html text/plain

如果您希望内容由多个过滤器处理，则它们的名称必须用分号分隔。也可以为每个过滤器使用一个AddOutputFilterByType指令。

下面的 configuration 导致标记为text/html的所有脚本输出首先由INCLUDES过滤器处理，然后由DEFLATE过滤器处理。

<Location "/cgi-bin/">
    Options Includes
    AddOutputFilterByType INCLUDES;DEFLATE text/html
</Location>

参见

• AddOutputFilter
• SetOutputFilter
• 过滤器

FilterChain 指令

这将从声明的过滤器配置实际过滤器链。FilterChain接受任意数量的 arguments，每个 arguments 可选地前面有一个 single-character 控件，用于确定要执行的操作：

• +filter-name
  将 filter-name 添加到过滤器链的末尾
• @filter-name
  在过滤器链的开头插入 filter-name
• -filter-name
  从过滤器链中删除 filter-name
• =filter-name
  清空过滤器链并 insert filter-name
• !
  清空过滤链
• filter-name
  相当于 filter-name

FilterDeclare 指令

该指令声明了一个输出过滤器以及将确定运行时 configuration 的头或环境变量。第一个参数是 filter-name，用于FilterProvider，FilterChain和FilterProtocol指令。

最终(可选)参数是过滤器的类型，并且取ap_filter_type的值-即RESOURCE(默认值)，CONTENT_SET，PROTOCOL，TRANSCODE，CONNECTION或NETWORK。

FilterProtocol 指令

这指示mod_filter处理确保过滤器不应该在不应该运行时运行，并且考虑到过滤器的影响正确设置 HTTP 响应 headers。

该指令有两种形式。有三个 arguments，它专门适用于该过滤器的 filter-name 和 provider-name。有两个 arguments，只要过滤器运行任何提供程序，它就适用于 filter-name。

使用此伪指令指定的标志与基础提供程序可能已使用mod_filter注册的标志合并。例如，过滤器可以在内部指定change=yes的等价物，但模块的特定配置可以用change=no覆盖。

proto-flags 是一个或多个

• change=yes|no
  指定过滤器是否更改内容，包括可能的内容长度。 2.4.7 及更高版本支持“no”参数。
• change=1:1
  过滤器更改内容，但不会更改内容长度
• byteranges=no
  过滤器无法在字节范围内工作，需要完整输入
• proxy=no
  过滤器不应该在代理 context 中运行
• proxy=transform
  过滤器以与 HTTP Cache-Control：no-transform 标头不兼容的方式转换响应。
• cache=no
  过滤器使输出不可缓存(例如，通过引入随机内容更改)

FilterProvider 指令

该指令注册智能过滤器的提供程序。当且仅当首次调用线束时声明的表达式求值为 true 时，才会调用提供程序。

必须通过 loading 一个用ap_register_output_filter注册 name 的模块来注册 provider-name。

表达式是ap_expr。

参见

• Apache HTTP Server 中的表达式，完整参考和示例。
• mod_include

FilterTrace 指令

该指令从mod_filter生成调试信息。它旨在帮助测试和调试提供程序(过滤器模块)，尽管它也可以帮助mod_filter本身。

调试输出取决于 level 集：

• 0(默认)
  没有生成调试信息。
• 1
  mod_filter 将在提供程序处理它们之前 record 桶和旅通过过滤器到错误 log。这类似于 mod_diagnostics 生成的信息。
• 2(尚未实施)
  将提交者之前的完整数据转储到临时文件。仅适用于 single-user 调试；这不会支持并发命中。