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

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

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

4.1. 剖析Header Filter
Anatomy of a Header Filter



    Header Filter由三个步骤组成：

   1. 决定何时操作响应
   2. 操作响应
   3. 调用下一个filter

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

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. 剖析Body Filter
Anatomy of a Body Filter

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


    一个body filter原型大概是这个样子（例子代码从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!-- Served by Nginx -->"。首先，我们需要判断给我们的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/$/<!-- Served by mod_perl -->/)，但是缓冲区链确实是一个强大的构想，它可以让程序员渐进地处理数据，这使得客户端可以尽可能早地得到响应。但是依我来看，缓冲区链表实在需要一个更为干净的接口，这样程序员也可以避免操作不一致状态的链表。但是目前为止，所有的操作风险都得自己控制。

4.3. Filter的装载
Filter Installation

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

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

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;
}

    发生了什么呢？好吧，如果你还记得，过滤模块组成了一条”接力链表“（CHAIN OF RESPONSIBILITY）。当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会第一个被执行。）

引用

边注: 这到底是怎么工作的?
     每个filter要么返回一个错误码，要么用下面的作为返回语句

return ngx_http_next_body_filter();

     因此，如果filter顺利链执行到了链尾（那个特别定义的的”write“filter），将返回一个"OK"响应，但如果执行过程中遇到了错误，链将被砍断，同时Nginx将给出一个错误的信息。这是一个单向的，错误快速返回的，只使用函数引用实现的链表。帅啊！