nginx模块开发入门（七）-3.2 Anatomy of an Upstream (a.k.a Proxy) Handler

zsy001

3.2. 剖析Upstream(又称 Proxy) Handler
Anatomy of an Upstream (a.k.a Proxy) Handler

    我已经帮你了解了如何让你的handler来产生响应。有些时候你可以用一小段C代码就可以得到响应，但是通常情况下你需要同另外一台server打交道（比如你正在写一个用来实现某种网络协议的模块）。你当然可以自己实现一套网络编程的东东，但是如果你只收到部分的响应，需要等待余下的响应数据，你会怎么办？你不会想阻塞整个事件处理循环吧？这样会毁掉Nginx的良好性能！幸运的是，Nginx允许你在它处理后端服务器（叫做"upstreams"）的机制上加入你的回调函数,因此你的模块将可以和其他的server通信,同时还不会妨碍其他的请求。这一节将介绍模块如何和一个upstream（如 Memcached, FastCGI,或者其它HTTP server）通信。
3.2.1. Upstream 回调函数概要
    与其他模块的回调处理函数不一样，upstream模块的处理函数几乎不做“实事”。它压根不调用ngx_http_output_filter。它仅仅是告诉回调函数什么时候可以向upstream server写数据了，以及什么时候能从upstream server读数据了。实际上它有6个可用的钩子：
    create_request 生成发送到upstream server的request buffer（或者一条缓冲链）
    reinit_request 在与后端服务器连接被重置的情况下（在create_request 被第二次调用之前）被调用
    process_header 处理upstream 响应的第一个bit，通常是保存一个指向upstream "payload"的指针
    abort_request 在客户端放弃请求时被调用
    finalize_request 在Nginx完成从upstream读取数据后调用
    input_filter 这是一个消息体的filter，用来处理响应消息体(例如把尾部删除)
    这些钩子是怎么勾上去的呢？下面是一个例子，简单版本的代理模块处理函数：

static ngx_int_t
ngx_http_proxy_handler(ngx_http_request_t *r)
{
ngx_int_t                   rc;
ngx_http_upstream_t        *u;
ngx_http_proxy_loc_conf_t  *plcf;
plcf = ngx_http_get_module_loc_conf(r, ngx_http_proxy_module);
/* set up our upstream struct */
u = ngx_pcalloc(r->pool, sizeof(ngx_http_upstream_t));
if (u == NULL) {
return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
u->peer.log = r->connection->log;
u->peer.log_error = NGX_ERROR_ERR;
u->output.tag = (ngx_buf_tag_t) &ngx_http_proxy_module;
u->conf = &plcf->upstream;
/* attach the callback functions */
u->create_request = ngx_http_proxy_create_request;
u->reinit_request = ngx_http_proxy_reinit_request;
u->process_header = ngx_http_proxy_process_status_line;
u->abort_request = ngx_http_proxy_abort_request;
u->finalize_request = ngx_http_proxy_finalize_request;
r->upstream = u;
rc = ngx_http_read_client_request_body(r, ngx_http_upstream_init);
if (rc >= NGX_HTTP_SPECIAL_RESPONSE) {
return rc;
}
return NGX_DONE;
}

    看上去都是些例行事务，不过重要的是那些回调函数。同时还要注意的是ngx_http_read_client_request_body，它又设置了一个回调函数，在Nginx完成从客户端读数据后会被调用。
    这些个回调函数都要做些什么工作呢？通常情况下，reinit_request, abort_request, 和 finalize_request用来设置或重置一些内部状态，但这些都是几行代码的事情。真正做苦力的是create_request 和 process_header。
3.2.2. create_request 回调函数
    简单起见，假设我有一个upstream server，它读入一个字符打印出两个字符。那么函数应该如何来写呢？
    create_request需要申请一个buffer来存放“一个字符”的请求，为buffer申请一个链表，并且把链表挂到upstream结构体上。看起来就像这样：

static ngx_int_t
ngx_http_character_server_create_request(ngx_http_request_t *r)
{
/* make a buffer and chain */
ngx_buf_t *b;
ngx_chain_t *cl;
b = ngx_create_temp_buf(r->pool, sizeof("a") - 1);
if (b == NULL)
return NGX_ERROR;
cl = ngx_alloc_chain_link(r->pool);
if (cl == NULL)
return NGX_ERROR;
/* hook the buffer to the chain */
cl->buf = b;
/* chain to the upstream */
r->upstream->request_bufs = cl;
/* now write to the buffer */
b->pos = "a";
b->last = b->pos + sizeof("a") - 1;
return NGX_OK;
}

    不是很难，对吧？当然实际应用中你很可能还会用到请求里面的URI。r->uri作为一个 ngx_str_t类型也是有效的，GET的参数在r->args中，最后别忘了你还能访问请求的header和 cookie信息。
3.2.3. process_header 回调函数
    现在轮到process_header了，就像create_request把链表指针挂到请求结构体上去一样，process_header把响应指针移到客户端可以接收到的部分。同时它还会从upstream 读入header信息，并且相应的设置发往客户端的响应headers。
    这里有个小例子，读进两个字符的响应。我们假设第一个字符代表“状态”字符。如果它是问号，我们将返回一个404错误并丢弃剩下的那个字符。如果它是空格，我们将以 200 OK的响应把另一个字符返回给客户端。好吧，这不是什么多有用的协议，不过可以作为一个不错的例子。那么我们如何来实现这个process_header 函数呢？

static ngx_int_t
ngx_http_character_server_process_header(ngx_http_request_t *r)
{
ngx_http_upstream_t       *u;
u = r->upstream;
/* read the first character */
switch(u->buffer.pos[0]) {
case '?':
r->header_only; /* suppress this buffer from the client */
u->headers_in.status_n = 404;
break;
case ' ':
u->buffer.pos++; /* move the buffer to point to the next character */
u->headers_in.status_n = 200;
break;
}
return NGX_OK;
}

     就是这样。操作头部，改变指针，搞定！注意headers_in实际上就是我们之前提到过的头部结构体（ http/ngx_http_request.h），但是它位于来自upstream的头中。一个真正的代理模块会在头信息的处理上做很多文章，不光是错误处理，做什么完全取决于你的想法。
    但是……如果一个buffer没有能够装下全部的从upstream来的头信息，该怎么办呢？
3.2.4. 状态保持 （Keeping state）
    好了，还记得我说过abort_request, reinit_request和finalize_request 可以用来重置内部状态吗？这是因为许多upstream模块都有其内部状态。模块需要定义一个 “自定义上下文结构” ，来标记目前为止从upstream读到了什么。这跟之前说的“模块上下文”不是一个概念。“模块上下文”是预定义类型，而“自定义上下文结构”可以包含任何你需要的数据和字段（这可是你自己定义的结构体）。这个结构体在create_request函数中被实例化，大概像这样：

ngx_http_character_server_ctx_t   *p;   /* my custom context struct */
p = ngx_pcalloc(r->pool, sizeof(ngx_http_character_server_ctx_t));
if (p == NULL) {
return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
ngx_http_set_ctx(r, p, ngx_http_character_server_module);


    最后一行实际上将“自定义上下文结构体”注册到了特定的请求和模块名上，以便在稍后取用。当你需要这个结构体时（可能所有的回调函数中都需要它），只需要：

ngx_http_proxy_ctx_t  *p;
p = ngx_http_get_module_ctx(r, ngx_http_proxy_module);


    指针 p 可以得到当前的状态. 设置、重置、增加、减少、往里填数据……你可以随心所欲的操作它。当upstream服务器返回一块一块的响应时，读取这些响应的过程中使用持久状态机是个很nx的办法，它不用阻塞主事件循环。很好很强大！