The nginx_lua module provides an API that can be called in the Lua code to interact with other NGINX components. The complete API is exposed in the form of two packages, namely, ngx and ndk. These packages are available within the ngx_lua directive and can be imported in external Lua modules using the require statements. The API has been integrated into the NGINX event loop, so all I/O operations in the Lua code must be performed using the exposed API to avoid performance bottlenecks.
The complete API is quite comprehensive and provides methods to interact with every feature of NGINX. It is available at http://wiki.nginx.org/HttpLuaModule#Nginx_API_for_Lua. The following section provides an overview of the exposed API.
The ngx.arg[i] API provides a way to access the variable/data passed to the Lua code:
- In the
set_by_luadirective, the variable holds the passed arguments - In the
body_filter_by_luadirective, the variable holds the response body and theeofflag
Any variable declared in an NGINX configuration can be accessed using the ngx.var.varName variable. The Lua code can read and write values in these variables. No new variables can be declared by Lua using this syntax.
The ngx.location.capture API is a function call that can be used to send a subrequest. The method takes the URI as the argument and returns a response containing the response header, response body, and response status. Optionally, we can also specify additional parameters, such as the HTTP method, arguments, and so on, in the function call.
The ngx.location.capture_multi API is similar to the ngx.location.capture API, but it can issue multiple, parallel subrequests to multiple URIs. The function takes input arguments as an array of URIs and option pairs. It returns multiple values—one for each URI passed. Here's an example:
res= ngx.location.capture('/call')
res1, res2, res3 = ngx.location.capture_multi{
{ "/call1", { args = "v1=1&v2=3" } },
{ "/call2" },
{ "/call3", { method = ngx.HTTP_POST, body = "Data" } }, }This API can be used to access/manipulate response headers. Besides modifying the existing headers, the Lua code can also define new header fields. Setting the value to nil clears the header field.
This API defines a number of methods in the ngx.req package that can be used to manipulate the current request. The following is a list of the available methods:
start_time: This returns the timestamp of when the request was created.http_version: This returns the HTTP version of the current request.raw_header: This returns the HTTP header of the current request.get_method/set_method: This retrieves/manipulates the current request's HTTP method.get_headers/set_header/clear_header: This retrieves/manipulates the current request's HTTP headers. Modifying or adding (new) a header field is allowed by the API. The header field can be removed by either setting the value tonilor by using theclear_headerfunction.read_body/discard_body: This API reads the current request body if it has not been read previously. If the body has been read earlier, the method returns immediately. Alternatively, the Lua code can discard a request by issuing thediscard_bodycall.get_body_data/set_body_data/get_post_args: These methods allow the Lua code to read and manipulate the response body as a string. If the request is a HTTP post request, then use theget_post_argsfunction call to get data as variables instead of strings.set_uri: This call can modify the URI of the current request. The method can also trigger new location matching in NGINX, such as the rewrite directive. By default, the location jumping is turned off.set_uri_args/get_uri_args: These methods can use the read and modify request query string. Thegetmethod returns the complete parameters as key-value pairs.
This API can be used to access a shared dictionary created by the lua_shared_dict directive. The dictionary has the following methods:
get/get_stale: This method returns the value for the key passed. If the key does not exist, the method returnsnull. If the key has expired, theget_stalemethod returns the expired value.set/safe_set: This method sets key-value pairs. Optionally, the method can also specify the expiry time during which the value would be valid. Thesetmethod would always override the value of the key even if it has not expired. Alternatively, thesafe_setmethod will never override a nonexpired value.flush_all/flush_expired: Theflush_allmethod marks all the items in the dictionary as expired. Theflush_expiredmethod frees up memory by removing all the expired items.delete: This removes a key-value pair from the dictionary.get_keys: This returns all keys to the dictionary.
This API can be used to work with a tcp or unix socket. The API is completely nonblocking in nature. It is important to note that the socket has the lifetime of the Lua code executing it. Thus, it cannot be shared across various Lua handlers.
The socket created by the API offers the following methods:
connect: This method connects to atcpsocket address or aunixsocket address.sslhandshake: This attempts an SSL handshake over the connection.send: This writes data over the wire.receive/receiveuntil: This receives data over the wire. Thereceiveuntilmethod returns an iterator that can be used to read a stream.close: This closes the connection.settimeout: This method sets a timeout for the next operation over the socket, namely connect, send, read, and so on.setkeepalive: This adds the connection to Lua's internal connection pool. The pool has a fixed size, specified as an argument insetkeepalive. If the pool exceeds the size, then the least recently used connection is automatically closed. The pool also specifies a lifetime for the connection, after which the connection is closed.
The socket is automatically closed when the Lua code exits or the socket lifetime expires. Any fatal error occurring over the socket will close the socket.