OpenResty之replace-filter-nginx-module

原文： openresty/replace-filter-nginx-module

1. 概要

location /t {
    default_type text/html;
    echo abc;
    replace_filter 'ab|abc' X;
}

location / {
    # proxy_pass/fastcgi_pass/...

    # caseless global substitution:
    replace_filter '\d+' 'blah blah' 'ig';
    replace_filter_types text/plain text/css;
}

location /a {
    # proxy_pass/fastcgi_pass/root/...

    # remove line-leading spaces and line-trailing spaces,
    # as well as blank lines:
    replace_filter '^\s+|\s+$' '' g;
}

location /b {
    # proxy_pass/fastcgi_pass/root/...

    # only remove line-leading spaces and line-trailing spaces:
    replace_filter '^[ \f\t]+|[ \f\t]+$' '' g;
}

location ~ '\.cpp$' {
    # proxy_pass/fastcgi_pass/root/...

    replace_filter_types text/plain;

    # skip C/C++ string literals:
    replace_filter "'(?:\\\\[^\n]|[^'\n])*'" $& g;
    replace_filter '"(?:\\\\[^\n]|[^"\n])*"' $& g;

    # remove all those ugly C/C++ comments:
    replace_filter '/\*.*?\*/|//[^\n]*' '' g;
}

2. 描述

该 Nginx 输出过滤模块尝试尽可能以非缓存模式执行正则表达式替换。

该模块没有使用像 PCRE 这样的传统回溯正则表达式 engines，而是使用由作者实现的新的 sregex 库，它从一开始就考虑了流处理。

sregex 支持 Perl 5 正则表达式的一个很好的公共子集。关于完整的功能列表，可查看 sregex 的文档: sregex Syntax Supported.

响应体数据仅在绝对必要时才进行缓存，例如面对属于数据块边界附近可能匹配的不完整捕获。

3. 指令

3.1 replace_filter

syntax: replace_filter <regex> <replace>

syntax: replace_filter <regex> <replace> <options>

defaultL no

context: http, server, location, location if

phase: output body filter

通过可选地正则标志指定正则模式和要被替换为的文本。

By default, the filter topped matching after the first match is found. This behavior can be changed by specifying the g regex option.

支持如下正则选项：

• g：全局搜索和替换（默认关闭该功能）
• i：不区分大小写（默认关闭）

在一个单独的字符串参数中可以联合多个选项，如下：

replace_filter hello hiya ig;

Nginx 变量可以插入到要替换的文本中，如下：

replace_filter \w+ "[$foo,$bar]";

如果要使用 '$' 字符，则使用 '$$'，例如：

replace_filter \w "$$";

支持使用子匹配捕获变量，如 $&, $1, $2 等等，如下示例：

replace_filter [bc]|d [$&-$1-$2] g;

子匹配捕获变量的语义与 Perl 5 语言完全相同。

在同一范围下支持多个 replace_filter 指令，所有的 pattern 将在 tokenizer 中同时应用。不会使用最长的 token 匹配语义，而是根据配置文件中的顺序对 pattern 进行优先级排序。

如下示例是从 C/C++ 源文件中删除所有的 C/C++ 注释：

replace_filter "'(?:\\\\[^\n]|[^'\n])*'" $& g;
replace_filter '"(?:\\\\[^\n]|[^"\n])*"' $& g;
replace_filter '/\*.*?\*/|//[^\n]*' '' g;

当 Content-Encoding 响应头部不为空（类似 gzip）时，响应主体将始终保持不变。因此，如果是 ngx_proxy 模块的话，通常需要在 nginx.conf 中添加如下行，以在后端服务器响应中禁用 gzip 压缩：

proxy_set_header Accept-Encoding '';

响应仍然可以在 Nginx 服务器级别上进行 gzip 压缩。

3.2 replace_filter_types

syntax: replace_filter_types <mime-type> ...

default: replace_filter_types text/html

context: http, server, location, location if

phase: output body filter

指定要被处理的一个或多个 MIME 类型（在 Content-Type 响应头部中）。

默认情况下，仅处理 text/html 类型的响应。

3.3 replace_filter_max_buffered_size

syntax: replace_filter_max_buffered_size <size>

default: replace_filter_max_buffered_size 8k

context: http, server, location, location if

phase: output body filter

限制模块在运行时缓冲的数据的总大小，默认为 8k。

当达到限制值时，replace_filter 将立即停止处理，并保留所有剩余的响应正文数据。

3.4 replace_filter_last_modified

syntax: replace_filter_last_modified keep | clear

default: replace_filter_last_modified clear

context: http, server, location, location if

phase: output body filter

控制如何去处理现有的 Last-Modified 响应头。

默认情况下，该模块将清除 Last-Modified 响应头（如果有）。可以通过指定如下行来保留原始的 Last-Modified 响应头:

replace_filter_last_modified keep;

3.5 replace_filter_skip

syntax: replace_filter_skip $var

default: no

context: http, server, location, location if

phase: output header filter

该指令控制是否基于每个请求跳过所有的 replace_filter 规则。

该指令支持常量值或者包含 Nginx 变量的字符串。

当在请求输出 header 阶段将值评估为空值（""）或者值 "0" 时，将不会跳过当前请求的 replace_filter 规则。否则，将会跳过当前请求的所有 replace_filter 规则。

如下一个简单的示例：

set $skip '';
location /t {
    content_by_lua '
        ngx.var.skip = 1
        ngx.say("abcabd")
    ';
    replace_filter_skip $skip;
    replace_filter abcabd X;
}

4. 安装

首先安装 sregex 库: https://github.com/agentzh/sregex

然后重新编译 Nginx：

./configure --add-module=/path/to/replace-filter-nginx-module

如果 sregex 不是安装在默认前缀路径下（如 /usr/local），则可以在执行 ./configure 脚本前，通过 SREGEX_INC 和 SREGEX_LIB 环境变量来指定 sregex 的安装位置。

export SREGEX_INC=/opt/sregex/include
export SREGEX_LIB=/opt/sregex/lib

从 Nginx 1.9.11 版本以上，可以在 ./configure 命令行上通过使用 --add-dynamic-module=PATH 选项来代替 --add-module=PATH ，从而将该模块编译为动态模块，然后在 ngxin.conf 上通过 load_module 指令显示加载该模块。

load_module /path/to/modules/ngx_http_replace_filter_module.so;