@@ -3747,14 +3747,187 @@ Nginx API for Lua
3747
3747
3748
3748
See also ngx.shared.DICT.
3749
3749
3750
+ ngx.socket.udp
3751
+ syntax: *udpsock = ngx.socket.udp()*
3752
+
3753
+ context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3754
+
3755
+ Creates and returns a UDP or datagram-oriented unix domain socket object
3756
+ (also known as one type of the "cosocket" objects). The following
3757
+ methods are supported on this object:
3758
+
3759
+ * setpeername
3760
+
3761
+ * send
3762
+
3763
+ * receive
3764
+
3765
+ * close
3766
+
3767
+ * settimeout
3768
+
3769
+ It is intended to be compatible with the UDP API of the LuaSocket
3770
+ (<http://w3.impa.br/~diego/software/luasocket/udp.html>) library but is
3771
+ 100% nonblocking out of the box.
3772
+
3773
+ This feature was first introduced in the "v0.5.7" release.
3774
+
3775
+ See also ngx.socket.tcp.
3776
+
3777
+ udpsock:setpeername
3778
+ syntax: *ok, err = udpsock:setpeername(host, port)*
3779
+
3780
+ syntax: *ok, err =
3781
+ udpsock:setpeername("unix:/path/to/unix-domain.socket")*
3782
+
3783
+ context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3784
+
3785
+ Attempts to connect a UDP socket object to a remote server or to a
3786
+ datagram unix domain socket file. Because the datagram protocol is
3787
+ actually connection-less, this method does not really establish a
3788
+ "connection", but only just set the name of the remote peer for
3789
+ subsequent read/write operations.
3790
+
3791
+ Both IP addresses and domain names can be specified as the "host"
3792
+ argument. In case of domain names, this method will use Nginx core's
3793
+ dynamic resolver to parse the domain name without blocking and it is
3794
+ required to configure the resolver directive in the "nginx.conf" file
3795
+ like this:
3796
+
3797
+ resolver 8.8.8.8; # use Google's public DNS nameserver
3798
+
3799
+ If the nameserver returns multiple IP addresses for the host name, this
3800
+ method will pick up one randomly.
3801
+
3802
+ In case of error, the method returns "nil" followed by a string
3803
+ describing the error. In case of success, the method returns 1.
3804
+
3805
+ Here is an example for connecting to a UDP (memcached) server:
3806
+
3807
+ location /test {
3808
+ resolver 8.8.8.8;
3809
+
3810
+ content_by_lua '
3811
+ local sock = ngx.socket.udp()
3812
+ local ok, err = sock:setpeername("my.memcached.server.domain", 11211)
3813
+ if not ok then
3814
+ ngx.say("failed to connect to memcached: ", err)
3815
+ return
3816
+ end
3817
+ ngx.say("successfully connected to memcached!")
3818
+ sock:close()
3819
+ ';
3820
+ }
3821
+
3822
+ Connecting to a datagram unix domain socket file is also possible:
3823
+
3824
+ local sock = ngx.socket.udp()
3825
+ local ok, err = sock:setpeername("unix:/tmp/some-datagram-service.sock")
3826
+ if not ok then
3827
+ ngx.say("failed to connect to the datagram unix domain socket: ", err)
3828
+ return
3829
+ end
3830
+
3831
+ assuming the datagram service is listening on the unix domain socket
3832
+ file "/tmp/some-datagram-service.sock".
3833
+
3834
+ Calling this method on an already connected socket object will cause the
3835
+ original connection to be closed first.
3836
+
3837
+ This method was first introduced in the "v0.5.7" release.
3838
+
3839
+ udpsock:send
3840
+ syntax: *ok, err = udpsock:send(data)*
3841
+
3842
+ context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3843
+
3844
+ Sends data on the current UDP or datagram unix domain socket object.
3845
+
3846
+ In case of success, it returns 1. Otherwise, it returns "nil" and a
3847
+ string describing the error.
3848
+
3849
+ The input argument "data" can either be a Lua string or a (nested) Lua
3850
+ table holding string fragments. In case of table arguments, this method
3851
+ will automatically copy all the string elements piece by piece to the
3852
+ underlying Nginx socket send buffers, which is usually optimal than
3853
+ doing string concatenation operations on the Lua land.
3854
+
3855
+ This feature was first introduced in the "v0.5.7" release.
3856
+
3857
+ udpsock:receive
3858
+ syntax: *data, err = udpsock:receive(size?)*
3859
+
3860
+ context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3861
+
3862
+ Receives data from the UDP or datagram unix domain socket object with an
3863
+ optional receive buffer size argument, "size".
3864
+
3865
+ This method is a synchronous operation and is 100% nonblocking.
3866
+
3867
+ In case of success, it returns the data received; in case of error, it
3868
+ returns "nil" with a string describing the error.
3869
+
3870
+ If the "size" argument is specified, then this method will use this size
3871
+ as the receive buffer size. But when this size is greater than 8192,
3872
+ then 8192 will be used instead.
3873
+
3874
+ If no argument is specified, then the maximal buffer size, 8192 is
3875
+ assumed.
3876
+
3877
+ Timeout for the reading operation is controlled by the
3878
+ lua_socket_read_timeout config directive and the settimeout method. And
3879
+ the latter takes priority. For example:
3880
+
3881
+ sock:settimeout(1000) -- one second timeout
3882
+ local data, err = sock:receive()
3883
+ if not data then
3884
+ ngx.say("failed to read a packet: ", data)
3885
+ return
3886
+ end
3887
+ ngx.say("successfully read a packet: ", data)
3888
+
3889
+ It is important here to call the settimeout method *before* calling this
3890
+ method.
3891
+
3892
+ This feature was first introduced in the "v0.5.7" release.
3893
+
3894
+ udpsock:close
3895
+ syntax: *ok, err = udpsock:close()*
3896
+
3897
+ context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3898
+
3899
+ Closes the current UDP or datagram unix domain socket. It returns the 1
3900
+ in case of success and returns "nil" with a string describing the error
3901
+ otherwise.
3902
+
3903
+ For socket objects that have not invoked this method, they (and their
3904
+ connections) will be automatically closed when the socket object is
3905
+ released by the Lua GC (Garbage Collector) or the current client HTTP
3906
+ request finishes processing.
3907
+
3908
+ This feature was first introduced in the "v0.5.7" release.
3909
+
3910
+ udpsock:settimeout
3911
+ syntax: *udpsock:settimeout(time)*
3912
+
3913
+ context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3914
+
3915
+ Set the timeout value in milliseconds for subsequent socket operations
3916
+ (like receive).
3917
+
3918
+ Settings done by this method takes priority over those config
3919
+ directives, like lua_socket_read_timeout.
3920
+
3921
+ This feature was first introduced in the "v0.5.7" release.
3922
+
3750
3923
ngx.socket.tcp
3751
3924
syntax: *tcpsock = ngx.socket.tcp()*
3752
3925
3753
3926
context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3754
3927
3755
- Creates and returns a TCP ( or Unix Domain) socket object (also known as
3756
- the "cosocket" object ). The following methods are supported on this
3757
- object:
3928
+ Creates and returns a TCP or stream-oriented unix domain socket object
3929
+ (also known as one type of the "cosocket" objects ). The following
3930
+ methods are supported on this object:
3758
3931
3759
3932
* connect
3760
3933
@@ -3781,15 +3954,17 @@ Nginx API for Lua
3781
3954
3782
3955
This feature was first introduced in the "v0.5.0rc1" release.
3783
3956
3957
+ See also ngx.socket.udp.
3958
+
3784
3959
tcpsock:connect
3785
3960
syntax: *ok, err = tcpsock:connect(host, port)*
3786
3961
3787
3962
syntax: *ok, err = tcpsock:connect("unix:/path/to/unix-domain.socket")*
3788
3963
3789
3964
context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
3790
3965
3791
- Attempts to connect a TCP socket object to a remote server or to a unix
3792
- domain socket file without blocking.
3966
+ Attempts to connect a TCP socket object to a remote server or to a
3967
+ stream unix domain socket file without blocking.
3793
3968
3794
3969
Before actually resolving the host name and connecting to the remote
3795
3970
backend, this method will always look up the connection pool for matched
@@ -3870,7 +4045,7 @@ Nginx API for Lua
3870
4045
In case of success, it returns the total number of bytes that have been
3871
4046
sent. Otherwise, it returns "nil" and a string describing the error.
3872
4047
3873
- The input argument ` data` can either be a Lua string or a (nested) Lua
4048
+ The input argument " data" can either be a Lua string or a (nested) Lua
3874
4049
table holding string fragments. In case of table arguments, this method
3875
4050
will automatically copy all the string elements piece by piece to the
3876
4051
underlying Nginx socket send buffers, which is usually optimal than
@@ -4059,19 +4234,19 @@ Nginx API for Lua
4059
4234
4060
4235
context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
4061
4236
4062
- Closes the current TCP or Unix Domain socket. It returns the 1 in case
4063
- of success and returns "nil" with a string describing the error
4237
+ Closes the current TCP or stream unix domain socket. It returns the 1 in
4238
+ case of success and returns "nil" with a string describing the error
4064
4239
otherwise.
4065
4240
4066
4241
For socket objects that have invoked the setkeepalive method, there is
4067
4242
no need to call this method on it because the socket object is already
4068
- closed (and the current connection is saved into the builtin connection
4243
+ closed (and the current connection is saved into the built-in connection
4069
4244
pool).
4070
4245
4071
- For socket objects that have not invoked setkeepalive, they (and their
4072
- connections) will be automatically closed when the socket object is
4073
- released by the Lua GC (Garbage Collector) or the current client HTTP
4074
- request finishes processing.
4246
+ For socket objects that have not invoked setkeepalive nor this method,
4247
+ they (and their connections) will be automatically closed when the
4248
+ socket object is released by the Lua GC (Garbage Collector) or the
4249
+ current client HTTP request finishes processing.
4075
4250
4076
4251
This feature was first introduced in the "v0.5.0rc1" release.
4077
4252
@@ -4380,6 +4555,18 @@ Data Sharing within an Nginx Worker
4380
4555
(<http://github.com/FRiCKLE/ngx_postgres/>) modules for details
4381
4556
4382
4557
Known Issues
4558
+ TCP socket connect operation issues
4559
+ The <tcpsock:connect|/"tcpsock:connect"> method may indicate "success"
4560
+ despite connection failures such as with "Connection Refused" errors.
4561
+
4562
+ However, later attempts to manipulate the cosocket object will fail and
4563
+ return the actual error status message generated by the failed
4564
+ connecting operation.
4565
+
4566
+ This issue appears to be due to limitations in the Nginx event model
4567
+ that only affect Mac OS X and *not* other operating systems like Linux
4568
+ and FreeBSD.
4569
+
4383
4570
Lua Coroutine Yielding/Resuming
4384
4571
* As the module's predefined Nginx I/O API uses the coroutine
4385
4572
yielding/resuming mechanism, user code should not call any Lua
@@ -4549,14 +4736,6 @@ Known Issues
4549
4736
if m then ngx.say(m[0]) else ngx.say("not matched!") end
4550
4737
-- evaluates to "1234"
4551
4738
4552
- Connecting Failures on Mac OS X
4553
- * Due to the limitations in the Nginx event model, the
4554
- <tcpsock:connect|/"tcpsock:connect"> method may return success upon
4555
- connecting failures like "Connection Refused" errors. But later
4556
- manipulation of the cosocket object will (correctly) fail with the
4557
- error message of the connecting operation. This issue has not yet
4558
- been observied on other operating systems like Linux and FreeBSD.
4559
-
4560
4739
Typical Uses
4561
4740
Just to name a few:
4562
4741
0 commit comments