658
658
This directive was first introduced in the <code>v0.3.1rc22</code> release.
660
== lua_socket_connect_timeout ==
662
'''syntax:''' ''lua_socket_connect_timeout <time>''
664
'''default:''' ''lua_socket_connect_timeout 60s''
666
'''context:''' ''http, server, location''
668
This directive controls the default timeout value used in TCP/unix-domain socket object's [[#tcpsock:connect|connect]] method and can be overridden by the [[#tcpsock:settimeout|settimeout]] method.
670
The <code><time></code> argument can be an integer, with an optional time unit, like <code>s</code> (second), <code>ms</code> (millisecond), <code>m</code> (minute). The default time unit is <code>s</code>, i.e., "second". The default setting is <code>60s</code>.
672
This directive was first introduced in the <code>v0.5.0rc1</code> release.
674
== lua_socket_send_timeout ==
676
'''syntax:''' ''lua_socket_send_timeout <time>''
678
'''default:''' ''lua_socket_send_timeout 60s''
680
'''context:''' ''http, server, location''
682
Controls the default timeout value used in TCP/unix-domain socket object's [[#tcpsock:send|send]] method and can be overridden by the [[#tcpsock:settimeout|settimeout]] method.
684
The <code><time></code> argument can be an integer, with an optional time unit, like <code>s</code> (second), <code>ms</code> (millisecond), <code>m</code> (minute). The default time unit is <code>s</code>, i.e., "second". The default setting is <code>60s</code>.
686
This directive was first introduced in the <code>v0.5.0rc1</code> release.
688
== lua_socket_send_lowat ==
690
'''syntax:''' ''lua_socket_send_lowat <size>''
692
'''default:''' ''lua_socket_send_lowat 0''
694
'''context:''' ''http, server, location''
696
Controls the <code>lowat</code> (low water) value for the cosocket send buffer.
698
== lua_socket_read_timeout ==
700
'''syntax:''' ''lua_socket_read_timeout <time>''
702
'''default:''' ''lua_socket_read_timeout 60s''
704
'''context:''' ''http, server, location''
706
'''phase:''' ''depends on usage''
708
This directive controls the default timeout value used in TCP/unix-domain socket object's [[#tcpsock:receive|receive]] method and iterator functions returned by the [[#tcpsock:receiveuntil|receiveuntil]] method. This setting can be overridden by the [[#tcpsock:settimeout|settimeout]] method.
710
The <code><time></code> argument can be an integer, with an optional time unit, like <code>s</code> (second), <code>ms</code> (millisecond), <code>m</code> (minute). The default time unit is <code>s</code>, i.e., "second". The default setting is <code>60s</code>.
712
This directive was first introduced in the <code>v0.5.0rc1</code> release.
714
== lua_socket_buffer_size ==
716
'''syntax:''' ''lua_socket_buffer_size <size>''
718
'''default:''' ''lua_socket_buffer_size 4k/8k''
720
'''context:''' ''http, server, location''
722
Specifies the buffer size used by cosocket reading operations.
724
This buffer does not have to be that big to hold everything at the same time because cosocket supports 100% non-buffered reading and parsing. So even <code>1</code> byte buffer size should still work everywhere but the performance could be bad.
726
This directive was first introduced in the <code>v0.5.0rc1</code> release.
728
== lua_socket_pool_size ==
730
'''syntax:''' ''lua_socket_pool_size <size>''
732
'''default:''' ''lua_socket_pool_size 30''
734
'''context:''' ''http, server, location''
736
Specifies the size limit (in terms of connection count) for every cosocket connection pool associated with every remote server (i.e., identified by either the host-port pair or the unix domain socket file path).
738
Default to 30 connections for every pool.
740
When the connection pool is exceeding the size limit, the least recently used (idle) connection already in the pool will be closed automatically to make room for the current connection.
742
Note that the cosocket connection pool is per nginx worker process rather than per nginx server instance, so so size limit specified here also applies to every single nginx worker process.
744
This directive was first introduced in the <code>v0.5.0rc1</code> release.
746
== lua_socket_keepalive_timeout ==
748
'''syntax:''' ''lua_socket_keepalive_timeout <time>''
750
'''default:''' ''lua_socket_keepalive_timeout 60s''
752
'''context:''' ''http, server, location''
754
This directive controls the default maximal idle time of the connections in the cosocket built-in connection pool. When this timeout reaches, idle connections will be closed automatically and removed from the pool. This setting can be overridden by cosocket objects' [[#tcpsock:setkeepalive|setkeepalive]] method.
756
The <code><time></code> argument can be an integer, with an optional time unit, like <code>s</code> (second), <code>ms</code> (millisecond), <code>m</code> (minute). The default time unit is <code>s</code>, ie, "second". The default setting is <code>60s</code>.
758
This directive was first introduced in the <code>v0.5.0rc1</code> release.
760
== lua_http10_buffering ==
762
'''syntax:''' ''lua_http10_buffering on|off''
764
'''default:''' ''lua_http10_buffering on''
766
'''context:''' ''http, server, location, location-if''
768
Enables or disables the automatic response caching for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper <code>Content-Length</code> response header.
770
If the Lua code explicitly sets a <code>Content-Length</code> response header before sending the headers (either explicity via [[#ngx.send_headers|ngx.send_headers]] or implicitly via the first [[#ngx.say|ngx.say]] or [[#ngx.print|ngx.print]] call).
772
If you want to output huge response data in a streaming fashion (via the [[#ngx.flush|ngx.flush]] call, for example), then you MUST turn off this directive to prevent memory footprint boost.
774
This directive is turned <code>on</code> by default.
776
THis directive was first introduced in the <code>v0.5.0rc19</code> release.
660
778
= Nginx API for Lua =
661
779
== Introduction ==
662
780
The various <code>*_by_lua</code> and <code>*_by_lua_file</code> configuration directives serve as gateways to the Lua API within the <code>nginx.conf</code> file. The Nginx Lua API described below can only be called within the user Lua code run in the context of these configuration directives.
2798
2977
See also [[#ngx.shared.DICT|ngx.shared.DICT]].
2979
== ngx.shared.DICT.flush_all ==
2980
'''syntax:''' ''ngx.shared.DICT:flush_all()''
2982
'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*''
2984
Flushes out all the items in the dictionary.
2986
This feature was first introduced in the <code>v0.5.0rc17</code> release.
2988
See also [[#ngx.shared.DICT|ngx.shared.DICT]].
2990
== ngx.socket.tcp ==
2991
'''syntax:''' ''tcpsock = ngx.socket.tcp()''
2993
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
2995
Creates and returns a TCP (or Unix Domain) socket object (also known as the "cosocket" object). The following methods are supported on this object:
2997
* [[#tcpsock:connect|connect]]
2998
* [[#tcpsock:send|send]]
2999
* [[#tcpsock:receive|receive]]
3000
* [[#tcpsock:close|close]]
3001
* [[#tcpsock:settimeout|settimeout]]
3002
* [[#tcpsock:setoption|setoption]]
3003
* [[#tcpsock:receiveuntil|receiveuntil]]
3004
* [[#tcpsock:setkeepalive|setkeepalive]]
3005
* [[#tcpsock:getreusedtimes|getreusedtimes]]
3007
It is intended to be compatible with the TCP API of the [http://w3.impa.br/~diego/software/luasocket/tcp.html LuaSocket] library but is 100% nonblocking out of the box. Also, we introduce some new APIs to provide more functionalities.
3009
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3011
== tcpsock:connect ==
3012
'''syntax:''' ''ok, err = tcpsock:connect(host, port)''
3014
'''syntax:''' ''ok, err = tcpsock:connect("unix:/path/to/unix-domain.socket")''
3016
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3018
Attempts to connect a TCP socket object to a remote server or to a unix domain socket file nonblockingly.
3020
Before actually resolving the host name and connecting to the remote backend, this method will always look up the connection pool for matched idle connections created by previous calls of this method (or the [[#ngx.socket.connect|ngx.socket.connect]] function).
3022
Both IP addresses and domain names can be specified as the <code>host</code> argument. In case of domain names, this method will use Nginx core's dynamic resolver to parse the domain name nonblockingly and it is required to configure the [[HttpCoreModule#resolver|resolver]] directive in your <code>nginx.conf</code> file like this:
3024
<geshi lang="nginx">
3025
resolver 8.8.8.8; # use Google's public DNS nameserver
3028
If the nameserver returns multiple IP addresses for the host name, this method will pick up one randomly.
3030
In case of error, the method returns <code>nil</code> followed by a string describing the error. In case of success, the method returns <code>1</code>.
3032
Here is an example for connecting to a TCP server:
3034
<geshi lang="nginx">
3039
local sock = ngx.socket.tcp()
3040
local ok, err = sock:connect("www.google.com", 80)
3042
ngx.say("failed to connect to google: ", err)
3045
ngx.say("successfully connected to google!")
3051
Connecting to a Unix Domain Socket file is also possible:
3054
local sock = ngx.socket.tcp()
3055
local ok, err = sock:connect("unix:/tmp/memcached.sock")
3057
ngx.say("failed to connect to the memcached unix domain socket: ", err)
3062
assuming that your memcached (or something else) is listening on the unix domain socket file <code>/tmp/memcached.sock</code>.
3064
Timeout for the connecting operation is controlled by the [[#lua_socket_connect_timeout|lua_socket_connect_timeout]] config directive and the [[#tcpsock:settimeout|settimeout]] method. And the latter takes priority. For example:
3067
local sock = ngx.socket.tcp()
3068
sock:settimeout(1000) -- one second timeout
3069
local ok, err = sock:connect(host, port)
3072
It is important here to call the [[#tcpsock:settimeout|settimeout]] method ''before'' calling this method.
3074
Calling this method on an already connected socket object will cause the original connection to be closed first.
3076
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3079
'''syntax:''' ''bytes, err = tcpsock:send(data)''
3081
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3083
Sends data nonblockingly on the current TCP or Unix Domain Socket connection.
3085
This method is a synchronous operation that will not return until ''all'' the data has been flushed into the system socket send buffer or an error occurs.
3087
In case of success, it returns the total number of bytes that have been sent. Otherwise, it returns <code>nil</code> and a string describing the error.
3089
The input argument `data` can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will automatically copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
3091
Timeout for the sending operation is controlled by the [[#lua_socket_send_timeout|lua_socket_send_timeout]] config directive and the [[#tcpsock:settimeout|settimeout]] method. And the latter takes priority. For example:
3094
sock:settimeout(1000) -- one second timeout
3095
local bytes, err = sock:send(request)
3098
It is important here to call the [[#tcpsock:settimeout|settimeout]] method ''before'' calling this method.
3100
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3102
== tcpsock:receive ==
3103
'''syntax:''' ''data, err, partial = tcpsock:receive(size)''
3105
'''syntax:''' ''data, err, partial = tcpsock:receive(pattern?)''
3107
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3109
Receives data from the connected socket according to the reading pattern or size.
3111
This method is a synchronous operation just like the [[#tcpsock:send|send]] method and is 100% nonblocking.
3113
In case of success, it returns the data received; in case of error, it returns <code>nil</code> with a string describing the error and the partial data received so far.
3115
If a number-like argument is specified (including strings that look like numbers), then it is interpreted as a size. This method will not return until it reads exactly this size of data or an error occurs.
3117
If a non-number-like string argument is specified, then it is interpreted as a "pattern". The following patterns are supported:
3119
* <code>'*a'</code>: reads from the socket until the connection is closed. No end-of-line translation is performed;
3120
* <code>'*l'</code>: reads a line of text from the socket. The line is terminated by a <code>Line Feed</code> (LF) character (ASCII 10), optionally preceded by a <code>Carriage Return</code> (CR) character (ASCII 13). The CR and LF characters are not included in the returned line. In fact, all CR characters are ignored by the pattern.
3122
If no argument is specified, then it is assumed to be the pattern <code>'*l'</code>, that is, the line reading pattern.
3124
Timeout for the reading operation is controlled by the [[#lua_socket_read_timeout|lua_socket_read_timeout]] config directive and the [[#tcpsock:settimeout|settimeout]] method. And the latter takes priority. For example:
3127
sock:settimeout(1000) -- one second timeout
3128
local line, err, partial = sock:receive()
3130
ngx.say("failed to read a line: ", err)
3133
ngx.say("successfully read a line: ", line)
3136
It is important here to call the [[#tcpsock:settimeout|settimeout]] method ''before'' calling this method.
3138
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3140
== tcpsock:receiveuntil ==
3141
'''syntax:''' ''iterator = tcpsock:receiveuntil(pattern)''
3143
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3145
This method returns an iterator Lua function that can be called to read the data stream until it sees the specified pattern or an error occurs.
3147
Here is an example for using this method to read a data stream with the boundary sequence <code>--abcedhb</code>:
3150
local reader = sock:receiveuntil("\r\n--abcedhb")
3151
local data, err, partial = reader()
3153
ngx.say("failed to read the data stream: ", err)
3155
ngx.say("read the data stream: ", data)
3158
When called without any argument, the iterator function returns the received data right ''before'' the specified pattern string in the incoming data stream. So for the example above, if the incoming data stream is <code>'hello, world! -agentzh\r\n--abcedhb blah blah'</code>, then the string <code>'hello, world! -agentzh'</code> will be returned.
3160
In case of error, the iterator function will return <code>nil</code> along with a string describing the error and the partial data bytes that have been read so far.
3162
The iterator function can be called multiple times and can be mixed safely with other cosocket method calls or other iterator function calls.
3164
The iterator function behaves differently (i.e., like a real iterator) when it is called with a <code>size</code> argument. That is, it will read that <code>size</code> of data at earch invocation and will return <code>nil</code> at the last invocation (either sees the boundary pattern or meets an error). For the last successful invocation of the iterator function, the <code>err</code> return value will be <code>nil</code> too. The iterator function will automatically reset after its last successful invocation that returns <code>nil</code> data and <code>nil</code> error. Consider the following example:
3167
local reader = sock:receiveuntil("\r\n--abcedhb")
3170
local data, err, partial = reader(4)
3173
ngx.say("failed to read the data stream: ", err)
3177
ngx.say("read done")
3180
ngx.say("read chunk: [", data, "]")
3184
Then for the incoming data stream <code>'hello, world! -agentzh\r\n--abcedhb blah blah'</code>, we shall get the following output from the sample code above:
3196
Note that, the actual data returned ''might'' be a little longer than the size limit specified by the <code>size</code> argument when your boundary pattern has ambiguity for streaming parsing. Near the boundary of the data stream, the data string actually returned could also be shorter than the size limit.
3198
Timeout for the iterator function's reading operation is controlled by the [[#lua_socket_read_timeout|lua_socket_read_timeout]] config directive and the [[#tcpsock:settimeout|settimeout]] method. And the latter takes priority. For example:
3201
local readline = sock:receiveuntil("\r\n")
3203
sock:settimeout(1000) -- one second timeout
3204
line, err, partial = readline()
3206
ngx.say("failed to read a line: ", err)
3209
ngx.say("successfully read a line: ", line)
3212
It is important here to call the [[#tcpsock:settimeout|settimeout]] method ''before'' calling the iterator function (note that the <code>receiveuntil</code> call is irrelevant here).
3214
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3217
'''syntax:''' ''ok, err = tcpsock:close()''
3219
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3221
Closes the current TCP or Unix Domain socket. It returns the <code>1</code> in case of success and returns <code>nil</code> with a string describing the error otherwise.
3223
For socket objects that have invoked the [[#tcpsock:setkeepalive|setkeepalive]] method, there is no need to call this method on it because the socket object is already closed (and the current connection is saved into the builtin connection pool).
3225
For socket objects that have not invoked [[#tcpsock:setkeepalive|setkeepalive]], they (and their connections) will be automatically closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
3227
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3229
== tcpsock:settimeout ==
3230
'''syntax:''' ''tcpsock:settimeout(time)''
3232
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3234
Set the timeout value in milliseconds for subsequent socket operations ([[#tcpsock:connect|connect]], [[#tcpsock:receive|receive]], and iterators returned from [[#tcpsock:receiveuntil|receiveuntil]]).
3236
Settings done by this method takes priority over those config directives, i.e., [[#lua_socket_connect_timeout|lua_socket_connect_timeout]], [[#lua_socket_send_timeout|lua_socket_send_timeout]], and [[#lua_socket_read_timeout|lua_socket_read_timeout]].
3238
Note that this method does ''not'' affect the [[#lua_socket_keepalive_timeout|lua_socket_keepalive_timeout]] setting; the <code>timeout</code> argument to the [[#tcpsock:setkeepalive|setkeepalive]] method should be used for this purpose instead.
3240
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3242
== tcpsock:setoption ==
3243
'''syntax:''' ''tcpsock:setoption(option, value?)''
3245
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3247
This function is added for [http://w3.impa.br/~diego/software/luasocket/tcp.html LuaSocket] API compatibility and does nothing for now. Its functionality will be implemented in future.
3249
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3251
== tcpsock:setkeepalive ==
3252
'''syntax:''' ''ok, err = tcpsock:setkeepalive(timeout?, size?)''
3254
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3256
Puts the current socket's connection into the cosocket built-in connection pool and keep it alive until other [[#tcpsock:connect|connect]] method calls request it or the associated maximal idle timeout is expired.
3258
The first optional argument, <code>timeout</code>, can be used to specify the maximal idle timeout (in milliseconds) for the current connection. If omitted, the default setting in the [[#lua_socket_keepalive_timeout|lua_socket_keepalive_timeout]] config directive will be used. If the <code>0</code> value is given, then the timeout interval is unlimited.
3260
The second optional argument, <code>size</code>, can be used to specify the maximal number of connections allowed in the connection pool for the current server (i.e., the current host-port pair or the unix domain socket file path). Note that the size of the connection pool cannot be changed once the pool is created. When this argument is omitted, the default setting in the [[#lua_socket_pool_size|lua_socket_pool_size]] config directive will be used.
3262
When the connection pool is exceeding the size limit, the least recently used (idle) connection already in the pool will be closed automatically to make room for the current connection.
3264
Note that the cosocket connection pool is per Nginx worker process rather than per Nginx server instance, so the size limit specified here also applies to every single Nginx worker process.
3266
Idle connections in the pool will be monitored for any exceptional events like connection abortion or unexpected incoming data on the line, in which cases the connection in question will be closed and removed from the pool.
3268
In case of success, this method returns <code>1</code>; otherwise, it returns <code>nil</code> and a string describing the error.
3270
This method also makes the current cosocket object enter the "closed" state, so you do not need to manually call the [[#tcpsock:close|close]] method on it afterwards.
3272
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3274
== tcpsock:getreusedtimes ==
3275
'''syntax:''' ''count, err = tcpsock:getreusedtimes()''
3277
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3279
This method returns the (successfully) reused times for the current connection. In case of error, it returns <code>nil</code> and a string describing the error.
3281
If the current connection does not come from the built-in connection pool, then this method always returns <code>0</code>, that is, the connection has never been reused (yet). If the connection comes from the connection pool, then the return value is always non-zero. So this method can also be used to determine if the current connection comes from the pool.
3283
This feature was first introduced in the <code>v0.5.0rc1</code> release.
3285
== ngx.socket.connect ==
3286
'''syntax:''' ''tcpsock, err = ngx.socket.connect(host, port)''
3288
'''syntax:''' ''tcpsock, err = ngx.socket.connect("unix:/path/to/unix-domain.socket")''
3290
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
3292
This function is a shortcut for combining [[#ngx.socket.tcp|ngx.socket.tcp()]] and the [[#tcpsock:connect|connect()]] method call in a single operation. It is actually implemented like this:
3295
local sock = ngx.socket.tcp()
3296
local ok, err = sock:connect(...)
3303
There is no way to use the [[#tcpsock:settimeout|settimeout]] method to specify connecting timeout for this method. You have to use the [[#lua_socket_connect_timeout|lua_socket_connect_timeout]] directive at configure time instead.
3305
This feature was first introduced in the <code>v0.5.0rc1</code> release.
2800
3307
== ndk.set_var.DIRECTIVE ==
2801
3308
'''syntax:''' ''res = ndk.set_var.DIRECTIVE_NAME''
added
removed
debian/modules/nginx-lua/doc/HttpLuaModule.wiki
