nginx模块开发入门（九） -4 Filters

4.Filters

注：本节事例http/modules/ngx_http_chunked_filter_module.c

Filter操作handler生成的响应。头部filter操作HTTP头，bodyfilter操作响应的内容。

4.1.剖析HeaderFilter

AnatomyofaHeaderFilter

HeaderFilter由三个步骤组成：

1.决定何时操作响应

2.操作响应

3.调用下一个filter

举个例子，比如有一个简化版本的"notmodified"headerfilter：如果客户请求头中的If-Modified-Since和响应头中的Last-Modified相符，它把响应状态设置成304。注意这个头部filter只读入一个参数：ngx_http_request_t结构体，而我们可以通过它操作到客户请求header和一会将被发送的响应responseheader。

static
ngx_int_t ngx_http_not_modified_header_filter(ngx_http_request_t *r)
{
    time_t  if_modified_since;

    if_modified_since = ngx_http_parse_time(r->headers_in.if_modified_since->value.data,
                              r->headers_in.if_modified_since->value.len);

/* step 1: decide whether to operate */
    if (if_modified_since != NGX_ERROR && 
        if_modified_since == r->headers_out.last_modified_time) {

/* step 2: operate on the header */
        r->headers_out.status = NGX_HTTP_NOT_MODIFIED;
        r->headers_out.content_type.len = 0;
        ngx_http_clear_content_length(r);
        ngx_http_clear_accept_ranges(r);
    }

/* step 3: call the next filter */
    return ngx_http_next_header_filter(r);
}

结构headers_out和我们在hander那一节中看到的是一样的（参考http/ngx_http_request.h），也可以随意处置。

4.2.剖析BodyFilter

AnatomyofaBodyFilter

因为bodyfilter一次只能操作一个bufferchain（链表），这使得编写bodyfilter需要一定的技巧。模块需要知道什么时候可以覆盖输入buffer，用新申请的buffer替换已有的，或者在现有的某个buffer前或后插入一个新buffer。有时候模块会收到许多buffer使得它不得不操作一个不完整的链表，这使得事情变得更加复杂了。而更加不幸的是，Nginx没有为我们提供上层的API来操作buffer链表，所以bodyfilter是比较难懂（当然也比较难写）。但是，有些操作你还是可以看出来的。

一个bodyfilter原型大概是这个样子（例子代码从Nginx源代码的“chunked”filter中取得）：

static ngx_int_t ngx_http_chunked_body_filter(ngx_http_request_t *r, ngx_chain_t *in);

第一个参数是我们的老朋友"请求结构体"(ngx_http_request_t)，第二个参数则是指向当前部分链表（chain）表头的指针（可能包含0，1，或更多的buffer）。

再来举个例子好了。假设我们想要做的是在每个请求之后插入文本"<l!--ServedbyNginx-->"。首先，我们需要判断给我们的buffer链表中是否已经包含响应的最终buffer。就像之前我说的，这里没有简便好用的API，所以我们只能自己来写个循环：

ngx_chain_t *chain_link;
    int chain_contains_last_buffer = 0;

    chain_link = in;
    for ( ; ; ) {
        if (chain_link->buf->last_buf)
            chain_contains_last_buffer = 1;
        if (chain_link->next == NULL)
            break;
        chain_link = chain_link->next;
    }

如果我们没有最后的缓冲区，就返回：

if (!chain_contains_last_buffer)
        return ngx_http_next_body_filter(r, in);

很好，现在最后一个缓冲区已经存在链表中了。接下来我们分配一个新缓冲区：

ngx_buf_t    *b;
    b = ngx_calloc_buf(r->pool);
    if (b == NULL) {
        return NGX_ERROR;
    }

把数据放进去:

b->pos = (u_char *) "<!-- Served by Nginx -->";
    b->last = b->pos + sizeof("<!-- Served by Nginx -->") - 1;

把这个缓冲区挂在新的链表上：

ngx_chain_t   *added_link;

    added_link = ngx_alloc_chain_link(r->pool);
    if (added_link == NULL)
        return NGX_ERROR;

    added_link->buf = b;
    added_link->next = NULL;

最后，把这个新链表挂在先前链表的末尾：

chain_link->next = added_link;

并根据变化重置变量"last_buf"的值：

chain_link->buf->last_buf = 0;
    added_link->buf->last_buf = 1;

再将修改过的链表传递给下一个输出过滤函数：

return ngx_http_next_body_filter(r, in);

现有的函数做了比我们更多的工作，比如mod_perl($response->body=~s/$/<!--Servedbymod_perl-->/)，但是缓冲区链确实是一个强大的构想，它可以让程序员渐进地处理数据，这使得客户端可以尽可能早地得到响应。但是依我来看，缓冲区链表实在需要一个更为干净的接口，这样程序员也可以避免操作不一致状态的链表。但是目前为止，所有的操作风险都得自己控制。

4.3.Filter的装载

FilterInstallation

Filter在回调函数post-configuration中被装载。headerfilter和bodyfilter都是在这里被装载的。

我们以chunkedfilter模块为例来具体看看：

static ngx_http_module_t  ngx_http_chunked_filter_module_ctx = {
    NULL,                                  /* preconfiguration */
    ngx_http_chunked_filter_init,          /* postconfiguration */
  ...
};

ngx_http_chunked_filter_init中的具体实现如下:

static ngx_int_t
ngx_http_chunked_filter_init(ngx_conf_t *cf)
{
    ngx_http_next_header_filter = ngx_http_top_header_filter;
    ngx_http_top_header_filter = ngx_http_chunked_header_filter;

    ngx_http_next_body_filter = ngx_http_top_body_filter;
    ngx_http_top_body_filter = ngx_http_chunked_body_filter;

    return NGX_OK;
}

发生了什么呢？好吧，如果你还记得，过滤模块组成了一条”接力链表“（CHAINOFRESPONSIBILITY）。当handler生成一个响应后，调用2个函数：ngx_http_output_filter它调用全局函数ngx_http_top_body_filter；

以及ngx_http_send_header它调用全局函数ngx_top_header_filter。

ngx_http_top_body_filter和ngx_http_top_header_filter是body和header各自的头部filter链的”链表头“。链表上的每一个”连接“都保存着链表中下一个连接的函数引用(分别是ngx_http_next_body_filter和ngx_http_next_header_filter)。当一个filter完成工作之后，它只需要调用下一个filter，直到一个特殊的被定义成”write“的filter被调用，这个”write“filter的作用是包装最终的HTTP响应。你在这个filter_init函数中看到的就是，模块把自己添加到filter链表中；它先把旧的”头部“filter当做是自己的”下一个“，然后再声明”它自己“是”头部“filter。（因此，最后一个被添加的filter会第一个被执行。）

return ngx_http_next_body_filter();