Writing hello module

In order to learn high-performance concurrent servers, I plan to study the implementation of Nginx. According to convention, you have to write a hello world program at the beginning, so the next step is to introduce how to write a simple HTTP module to print "Hello World" under the Nginx framework.

Define the processing of hello configuration items

First, we need to define a commands array to define the configuration file parameters of the module. Each array element is of type ngx_command_t, and the end of the array is terminated with ngx_null_command.

When Nginx parses a configuration item in the configuration file, it will first traverse all modules. For each module, it will traverse the commands array. Each ngx_command_t structure defines a configuration item that it is interested in. The structure is defined as follows:

<code><span>struct</span> ngx_command_s {
    <span>/* 配置项名称 */</span>
    ngx_str_t             name;
    <span>/* 指定配置项可以出现的位置 */</span>
    ngx_uint_t            type;
    <span>/* 出现了name中指定的配置项后，将会调用set方法处理配置项的参数 */</span><span>char</span>               *(*<span>set</span>)(ngx_conf_t *cf, ngx_command_t *cmd, <span>void</span> *conf);
    ngx_uint_t            conf;
    <span>/* 在配置文件中的偏移量 */</span>
    ngx_uint_t            offset;
    <span>/* 配置项读取后的处理过程，必须是ngx_conf_post_t结构的指针 */</span><span>void</span>                 *post;
};

<span>#define ngx_null_command  { ngx_null_string, 0, NULL, 0, 0, NULL }</span></code>

After understanding the commands array, we define the processing of the hello configuration item:

<code><span>static</span> ngx_command_t ngx_http_hello_commands[] = {

    {   ngx_string(<span>"hello"</span>),
        NGX_HTTP_LOC_CONF|NGX_CONF_NOARGS,
        ngx_http_hello,
        NGX_HTTP_LOC_CONF_OFFSET,
        <span>0</span>,
        NULL },

    ngx_null_command
};</code>

Among them, ngx_http_hello is the set member in the ngx_command_t structure. When the hello configuration item appears in a certain configuration block, Nginx will call the ngx_http_hello method. The following is the implementation of ngx_http_hello:

<code><span>static</span><span>char</span> *
ngx_http_hello(ngx_conf_t *cf, ngx_command_t *cmd, <span>void</span> *conf)
{
    ngx_http_core_loc_conf_t *clcf;

    <span>/* 首先找到hello配置项所属的配置块 */</span>
    clcf = ngx_http_conf_get_module_loc_conf(cf, ngx_http_core_module);

    <span>/* HTTP框架在处理用户请求进行到NGX_HTTP_CONTENT_PHASE阶段时
     * 如果请求的主机域名、URI与hello配置项所在的配置块相匹配
     * 则调用ngx_http_hello_handler方法处理这个请求
     */</span>
    clcf->handler = ngx_http_hello_handler;

    <span>return</span> NGX_CONF_OK;
}</code>

Define hello module

The way to define an HTTP module is very simple, just define an ngx_moodule_t structure as follows:

<code>ngx_module_t ngx_http_hello_module = {
    NGX_MODULE_V1,
    &ngx_http_hello_module_ctx,    <span>/* module context */</span>
    ngx_http_hello_commands,       <span>/* module directives */</span>
    NGX_HTTP_MODULE,               <span>/* module type */</span>
    NULL,                          <span>/* init master */</span>
    NULL,                          <span>/* init module */</span>
    NULL,                          <span>/* init process */</span>
    NULL,                          <span>/* init thread */</span>
    NULL,                          <span>/* exit thread */</span>
    NULL,                          <span>/* exit process */</span>
    NULL,                          <span>/* exit master */</span>
    NGX_MODULE_V1_PADDING
};</code>

The hello module will be added to the ngx_modules global at compile time in the array.

Among them ngx_http_hello_commands is the processing of the hello configuration item we defined in the previous section.

Because we are defining the HTTP module, type must be set to NGX_HTTP_MODULE.

There is also an important member void* ctx. For the HTTP module, the ctx pointer must point to the ngx_http_module_t interface.

The HTTP framework defines 8 stages described by the ngx_http_module_t interface when reading and reloading the configuration file. When the HTTP framework is started, it will call the corresponding method in ngx_http_module_t in each stage. If no work is required, it can be defined as NULL. Because the hello module does not need to do any work, it is defined as follows:

<code><span>static</span> ngx_http_module_t ngx_http_hello_module_ctx = {
    NULL,                          <span>/* preconfiguration */</span>
    NULL,                           <span>/* postconfiguration */</span>    NULL,                          <span>/* create main configuration */</span>
    NULL,                          <span>/* init main configuration */</span>    NULL,                          <span>/* create server configuration */</span>
    NULL,                          <span>/* merge server configuration */</span>    NULL,                           <span>/* create location configuration */</span>
    NULL                            <span>/* merge location configuration */</span>
};</code>

Processing user requests

The last step is to process user requests. This requires some knowledge of HTTP. You can refer to Introduction to HTTP Protocol. We handle the user's request by implementing the ngx_http_hello_handler method, which is defined as follows:

<code><span>static</span> ngx_int_t
ngx_http_hello_handler(ngx_http_request_t *r)</code>

where the ngx_http_request_t structure contains all the information of the request (such as method, URI, protocol version number and header, etc.) , in addition, it also contains many other members, such as memory pool, response header, etc.

Because we only deal with the GET method and the HEAD method, we need to make the following judgment:

<code><span>if</span> (!(r->method & (NGX_HTTP_GET | NGX_HTTP_HEAD))) {
        <span>return</span> NGX_HTTP_NOT_ALLOWED;
 }</code>

Next, because we don’t need the package body in the request, we need to discard the package body. The method is as follows:

<code>ngx_int_t rc = ngx_http_discard_request_body(r);
<span>if</span> (rc != NGX_OK) {
    <span>return</span> rc;
}</code>

Then set the returned Response package, the returned package body only contains a "Hello World" string:

<code>ngx_str_type = ngx_string(<span>"text/plain"</span>);
ngx_str_response = ngx_string(<span>"Hello World"</span>);
r->headers_out.status = NGX_HTTP_OK;
r->headers_out.content_length_n = response.len;
r->headers_out.content_type = type;</code>

Finally, the header and body of the response package are sent:

<code>    rc = ngx_http_send_header(r);
    <span>if</span> (rc == NGX_ERR || rc > NGX_OK || r->header_only) {
        <span>return</span> rc;
    }

    ngx_buf_t *b;
    b = ngx_create_temp_buf(r->pool, response.len);
    <span>if</span> (b == NULL) {
        <span>return</span> NGX_HTTP_INTERNAL_SERVER_ERROR;
    }

    ngx_memcpy(b->pos, response.data, response.len);
    b->last = b->pos + response.len;
    b->last_buf = <span>1</span>;

    ngx_chain_t out;
    out.buf = b;
    out.next = NULL;

    <span>/* send the buffer chain of your response */</span><span>return</span> ngx_http_output_filter(r, &out);</code>

The complete code can be viewed here: hello_module

Compile and run

Create a new config file in the same directory as the code, add the following lines:

<code>ngx_addon_name=ngx_http_hello_module
HTTP_MODULES=<span>"<span>$HTTP_MODULES</span> ngx_http_hello_module"</span>
NGX_ADDON_SRCS=<span>"<span>$NGX_ADDON_SRCS</span><span>$ngx_addon_dir</span>/ngx_http_hello_module.c"</span></code>

Then enter the Nginx source code root directory, run configure, remember to bring the –add-module parameter, and add our own writing after the parameter The path where the HTTP module code is located: After

<code>./configure --prefix=<span>/usr/local</span><span>/nginx --add-module=/code</span><span>/nginx-1.8.0/src</span><span>/http/hello</span>_module</code>

configure is completed, use the make command to compile. After successful compilation, enter make install to complete the installation.

Modify /usr/local/nginx/conf/nginx.conf, add:

<code>http{
    <span>...</span>
    server {
        <span>...</span>
        location /hello {
            hello;
        }
        <span>...</span>
    }
    <span>...</span>
}</code>

Run Nginx, and then enter IP/hello in the browser to see the "Hello World string" displayed.

Reference

"In-depth understanding of Nginx"

The above introduces the writing of the hello module, including various aspects. I hope it will be helpful to friends who are interested in PHP tutorials.