How to use the upstream module in Nginx

Upstream module introduction

• nginx modules are generally divided into three categories: handler, filter and upstream. In the previous chapters, readers have already learned about handlers and filters. Using these two types of modules, nginx can easily complete any stand-alone work.

• The upstream module will enable nginx to transcend the limitations of a single machine and complete the reception, processing and forwarding of network data.

• The data forwarding function provides nginx with horizontal processing capabilities across a single machine, freeing nginx from the limitation of only providing a single function for terminal nodes, and enabling it to have network application level disassembly. Divide, encapsulate and integrate functions.

• Data forwardingis a key component of nginx’s ability to build a network application. Of course, due to development cost issues, key components of a network application are often initially developed using high-level programming languages. But when the system reaches a certain scale and more emphasis is placed on performance, in order to achieve the required performance goals, the components developed in high-level languages must be structurally modified.

At this time, in terms of modification costs, nginx's upstream module shows its advantages because it is inherently fast. As an aside, the hierarchical and loose coupling provided by nginx's configuration system makes the system scalable to a relatively high level.

upstream module interface

Essentially speaking, upstream belongs to the handler, but it does not generate its own content, but obtains the content by requesting the back-end server, so it is called upstream (upstream) . The entire process of requesting and obtaining response content has been encapsulated within nginx, so the upstream module only needs to develop several callback functions to complete specific work such as constructing requests and parsing responses.

The upstream module callback functions are listed as follows:

memcached module analysis

• memcache is a high-performance distributed cache system that has been widely used. memcache defines a set of private communication protocols so that memcache cannot be accessed through HTTP requests. However, the protocol itself is simple and efficient, and memcache is widely used, so most modern development languages and platforms provide memcache support to facilitate developers to use memcache.

• nginx provides the ngx_http_memcached module, which provides the function of reading data from memcache, but does not provide the function of writing data to memcache.

The upstream module uses the access method of the handler module.

At the same time, the design of the instruction system of the upstream module also follows the basic rules of the handler module: the module will be executed only after configuring the module.

So, what is so special about the upstream module? That is the processing function of the upstream module. The operations performed by the processing function of the upstream module include a fixed process: (take the memcached module as an example, in the processing function ngx_http_memcached_handler of memcached)

Create the upstream data structure:

ngx_http_upstream_t *u; if (ngx_http_upstream_create(r) != NGX_OK) { return NGX_HTTP_INTERNAL_SERVER_ERROR; } u = r->upstream;

Set the tag and schema of the module. Schema will only be used for logs now, and tags will be used for buf_chain management:

ngx_str_set(&u->schema, "memcached://"); u->output.tag = (ngx_buf_tag_t) &ngx_http_memcached_module;

Set the upstream backend server list data structure:

mlcf = ngx_http_get_module_loc_conf(r, ngx_http_memcached_module); u->conf = &mlcf->upstream;

Set the upstream callback function:

u->create_request = ngx_http_memcached_create_request; u->reinit_request = ngx_http_memcached_reinit_request; u->process_header = ngx_http_memcached_process_header; u->abort_request = ngx_http_memcached_abort_request; u->finalize_request = ngx_http_memcached_finalize_request; u->input_filter_init = ngx_http_memcached_filter_init; u->input_filter = ngx_http_memcached_filter;

Create and set upstream environment data structure:

ctx = ngx_palloc(r->pool, sizeof(ngx_http_memcached_ctx_t)); if (ctx == NULL) { return NGX_HTTP_INTERNAL_SERVER_ERROR; } ctx->request = r; ngx_http_set_ctx(r, ctx, ngx_http_memcached_module); u->input_filter_ctx = ctx;

Complete upstream initialization and finishing work:

r->main->count++; ngx_http_upstream_init(r); return NGX_DONE;

This is true for any upstream module, as simple as memcached, as complex as proxy and fastcgi.
The biggest difference between different upstream modules in these 6 steps will appear in steps 2, 3, 4, and 5.

Steps 2 and 4 are easy to understand. The flags set by different modules and the callback functions used are definitely different. Step 5 is not difficult to understand either.

Only step 3 is a bit confusing. Different modules have very different strategies when obtaining the backend server list. Some are as simple and clear as memcached, and some are as logically complex as proxy.

Step 6 is usually consistent between different modules. Increase count by 1 and return NGX_DONE.
When nginx encounters this situation, although it will consider that the processing of the current request has ended, it will not release the memory resources used by the request, nor will it close the connection with the client.
The reason why this is needed is because nginx has established a one-to-one relationship between upstream requests and client requests. When subsequently using ngx_event_pipe to send the upstream response back to the client, these stored client information will also be used. data structure.
Bind upstream requests and client requests one-to-one. This design has advantages and disadvantages. The advantage is that it simplifies module development and allows you to focus on module logic. However, the disadvantages are equally obvious. One-to-one design often cannot meet the needs of complex logic.

Callback function:(still taking the processing function of the memcached module as an example)

• ngx_http_memcached_create_request: It is very simple to generate one according to the set content key, then generate a "get $key" request and place it in r->upstream->request_bufs.

• ngx_http_memcached_reinit_request: No initialization required.

• ngx_http_memcached_abort_request: No additional action required.

• ngx_http_memcached_finalize_request: No additional action required.

• ngx_http_memcached_process_header: The business focus function of the module. The header information of the memcache protocol is defined as the first line of text, and the code is as follows:

#define LF (u_char) '\n' for (p = u->buffer.pos; p < u->buffer.last; p++) { if (*p == LF) { goto found; } }

If the LF (‘\n’) character is not found in the data that has been read into the buffer , the function returns NGX_AGAIN, indicating that the header has not been completely read and the data needs to continue to be read. nginx will call this function again after receiving new data.

nginx will only use one cache when processing the response header of the back-end server. All data is in this cache, so when parsing the header information, there is no need to consider the fact that the header information spans multiple caches. If the header is too large and cannot be saved in this cache, nginx will return an error message to the client and record an error log, indicating that the cache is not large enough.

The important responsibility of ngx_http_memcached_process_header is to translate the status returned by the back-end server into the status returned to the client. For example:

u->headers_in.content_length_n = ngx_atoof(start, p - start); ··· u->headers_in.status_n = 200; u->state->status = 200; ··· u->headers_in.status_n = 404; u->state->status = 404;

u->state is used to calculate upstream related variables. For example, u->state->status will be used to calculate the value of the variable "upstream_status". u->headers_in will be returned as a status code in the response to the client. And u->headers_in.content_length_n sets the length of the response returned to the client.

In this function, you must move the read pointer pos backward after processing the header information, otherwise this data will also be copied to the body of the response returned to the client, resulting in the content of the body being inconsistent. correct.

ngx_http_memcached_process_header function completes the correct processing of the response header and should return NGX_OK. If NGX_AGAIN is returned, it means that the complete data has not been read and the data needs to be continued to be read from the backend server. Returning NGX_DECLINED is meaningless. Any other return value is considered an error status, and nginx will end the upstream request and return an error message.

ngx_http_memcached_filter_init: Fix content length received from backend server. Because this part of the length is not added when processing the header.

ngx_http_memcached_filter:
The memcached module is a rare module with a callback function for processing text.
Because the memcached module needs to filter the CRLF "END" CRLF at the end of the text, it implements its own filter callback function.

The actual meaning of processing the text is to encapsulate the valid content of the text received from the back-end server into ngx_chain_t and add it to the end of u->out_bufs.

nginx does not copy data, but establishes the ngx_buf_t data structure to point to these data memory areas, and then organizes these bufs by ngx_chain_t. This implementation avoids large-scale memory relocation and is one of the reasons why nginx is efficient.

The above is the detailed content of How to use the upstream module in Nginx. For more information, please follow other related articles on the PHP Chinese website!