Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
documented the UDP/datagram cosocket API.
  • Loading branch information
agentzh committed Jul 10, 2012
1 parent 0a2d1d2 commit 06abbea
Show file tree
Hide file tree
Showing 3 changed files with 516 additions and 39 deletions.
221 changes: 200 additions & 21 deletions README
Expand Up @@ -3747,14 +3747,187 @@ Nginx API for Lua

See also ngx.shared.DICT.

ngx.socket.udp
syntax: *udpsock = ngx.socket.udp()*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Creates and returns a UDP or datagram-oriented unix domain socket object
(also known as one type of the "cosocket" objects). The following
methods are supported on this object:

* setpeername

* send

* receive

* close

* settimeout

It is intended to be compatible with the UDP API of the LuaSocket
(<http://w3.impa.br/~diego/software/luasocket/udp.html>) library but is
100% nonblocking out of the box.

This feature was first introduced in the "v0.5.7" release.

See also ngx.socket.tcp.

udpsock:setpeername
syntax: *ok, err = udpsock:setpeername(host, port)*

syntax: *ok, err =
udpsock:setpeername("unix:/path/to/unix-domain.socket")*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Attempts to connect a UDP socket object to a remote server or to a
datagram unix domain socket file. Because the datagram protocol is
actually connection-less, this method does not really establish a
"connection", but only just set the name of the remote peer for
subsequent read/write operations.

Both IP addresses and domain names can be specified as the "host"
argument. In case of domain names, this method will use Nginx core's
dynamic resolver to parse the domain name without blocking and it is
required to configure the resolver directive in the "nginx.conf" file
like this:

resolver 8.8.8.8; # use Google's public DNS nameserver

If the nameserver returns multiple IP addresses for the host name, this
method will pick up one randomly.

In case of error, the method returns "nil" followed by a string
describing the error. In case of success, the method returns 1.

Here is an example for connecting to a UDP (memcached) server:

location /test {
resolver 8.8.8.8;

content_by_lua '
local sock = ngx.socket.udp()
local ok, err = sock:setpeername("my.memcached.server.domain", 11211)
if not ok then
ngx.say("failed to connect to memcached: ", err)
return
end
ngx.say("successfully connected to memcached!")
sock:close()
';
}

Connecting to a datagram unix domain socket file is also possible:

local sock = ngx.socket.udp()
local ok, err = sock:setpeername("unix:/tmp/some-datagram-service.sock")
if not ok then
ngx.say("failed to connect to the datagram unix domain socket: ", err)
return
end

assuming the datagram service is listening on the unix domain socket
file "/tmp/some-datagram-service.sock".

Calling this method on an already connected socket object will cause the
original connection to be closed first.

This method was first introduced in the "v0.5.7" release.

udpsock:send
syntax: *ok, err = udpsock:send(data)*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Sends data on the current UDP or datagram unix domain socket object.

In case of success, it returns 1. Otherwise, it returns "nil" and a
string describing the error.

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.

This feature was first introduced in the "v0.5.7" release.

udpsock:receive
syntax: *data, err = udpsock:receive(size?)*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Receives data from the UDP or datagram unix domain socket object with an
optional receive buffer size argument, "size".

This method is a synchronous operation and is 100% nonblocking.

In case of success, it returns the data received; in case of error, it
returns "nil" with a string describing the error.

If the "size" argument is specified, then this method will use this size
as the receive buffer size. But when this size is greater than 8192,
then 8192 will be used instead.

If no argument is specified, then the maximal buffer size, 8192 is
assumed.

Timeout for the reading operation is controlled by the
lua_socket_read_timeout config directive and the settimeout method. And
the latter takes priority. For example:

sock:settimeout(1000) -- one second timeout
local data, err = sock:receive()
if not data then
ngx.say("failed to read a packet: ", data)
return
end
ngx.say("successfully read a packet: ", data)

It is important here to call the settimeout method *before* calling this
method.

This feature was first introduced in the "v0.5.7" release.

udpsock:close
syntax: *ok, err = udpsock:close()*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Closes the current UDP or datagram unix domain socket. It returns the 1
in case of success and returns "nil" with a string describing the error
otherwise.

For socket objects that have not invoked this method, 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.

This feature was first introduced in the "v0.5.7" release.

udpsock:settimeout
syntax: *udpsock:settimeout(time)*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Set the timeout value in milliseconds for subsequent socket operations
(like receive).

Settings done by this method takes priority over those config
directives, like lua_socket_read_timeout.

This feature was first introduced in the "v0.5.7" release.

ngx.socket.tcp
syntax: *tcpsock = ngx.socket.tcp()*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Creates and returns a TCP (or Unix Domain) socket object (also known as
the "cosocket" object). The following methods are supported on this
object:
Creates and returns a TCP or stream-oriented unix domain socket object
(also known as one type of the "cosocket" objects). The following
methods are supported on this object:

* connect

Expand All @@ -3781,15 +3954,17 @@ Nginx API for Lua

This feature was first introduced in the "v0.5.0rc1" release.

See also ngx.socket.udp.

tcpsock:connect
syntax: *ok, err = tcpsock:connect(host, port)*

syntax: *ok, err = tcpsock:connect("unix:/path/to/unix-domain.socket")*

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Attempts to connect a TCP socket object to a remote server or to a unix
domain socket file without blocking.
Attempts to connect a TCP socket object to a remote server or to a
stream unix domain socket file without blocking.

Before actually resolving the host name and connecting to the remote
backend, this method will always look up the connection pool for matched
Expand Down Expand Up @@ -3870,7 +4045,7 @@ Nginx API for Lua
In case of success, it returns the total number of bytes that have been
sent. Otherwise, it returns "nil" and a string describing the error.

The input argument `data` can either be a Lua string or a (nested) Lua
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
Expand Down Expand Up @@ -4059,19 +4234,19 @@ Nginx API for Lua

context: *rewrite_by_lua*, access_by_lua*, content_by_lua**

Closes the current TCP or Unix Domain socket. It returns the 1 in case
of success and returns "nil" with a string describing the error
Closes the current TCP or stream unix domain socket. It returns the 1 in
case of success and returns "nil" with a string describing the error
otherwise.

For socket objects that have invoked the 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
closed (and the current connection is saved into the built-in connection
pool).

For socket objects that have not invoked 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.
For socket objects that have not invoked setkeepalive nor this method,
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.

This feature was first introduced in the "v0.5.0rc1" release.

Expand Down Expand Up @@ -4380,6 +4555,18 @@ Data Sharing within an Nginx Worker
(<http://github.com/FRiCKLE/ngx_postgres/>) modules for details

Known Issues
TCP socket connect operation issues
The <tcpsock:connect|/"tcpsock:connect"> method may indicate "success"
despite connection failures such as with "Connection Refused" errors.

However, later attempts to manipulate the cosocket object will fail and
return the actual error status message generated by the failed
connecting operation.

This issue appears to be due to limitations in the Nginx event model
that only affect Mac OS X and *not* other operating systems like Linux
and FreeBSD.

Lua Coroutine Yielding/Resuming
* As the module's predefined Nginx I/O API uses the coroutine
yielding/resuming mechanism, user code should not call any Lua
Expand Down Expand Up @@ -4549,14 +4736,6 @@ Known Issues
if m then ngx.say(m[0]) else ngx.say("not matched!") end
-- evaluates to "1234"

Connecting Failures on Mac OS X
* Due to the limitations in the Nginx event model, the
<tcpsock:connect|/"tcpsock:connect"> method may return success upon
connecting failures like "Connection Refused" errors. But later
manipulation of the cosocket object will (correctly) fail with the
error message of the connecting operation. This issue has not yet
been observied on other operating systems like Linux and FreeBSD.

Typical Uses
Just to name a few:

Expand Down

0 comments on commit 06abbea

Please sign in to comment.