tcpsockconnect.md

tcpsock:connect

语法: ok, err = tcpsock:connect(host, port, options_table?)

语法: ok, err = tcpsock:connect("unix:/path/to/unix-domain.socket", options_table?)

环境: rewrite_by_lua, access_by_lua*, content_by_lua*, ngx.timer.**

尝试以非阻塞的方式，对远端服务或 unix domain socket 文件建立 TCP socket 对象。

在真正解析主机名并连接到后端服务之前，该方法将永远优先在连接池内（都是调用该方法或 ngx.socket.connect 函数的连接）查找符合条件的空闲连接。

对 host 参数 IP 地址和域名在这里都是可以使用的。当使用域名时，该方法将使用 Nginx 内部的动态域名解析器（非阻塞并且需要在 nginx.conf 文件中配置 resolver 指令），例如：

 resolver 8.8.8.8;  # 使用 Google 的公用域名解析服务器

如果域名服务器对这个主机名返回多个 IP 地址，该方法将从中随机挑选一个。

错误情况下，该方法返回 nil 及错误描述信息。成功情况下，该方法返回 1 。

这里是个连接到 TCP 服务的示例：

 location /test {
     resolver 8.8.8.8;

     content_by_lua '
         local sock = ngx.socket.tcp()
         local ok, err = sock:connect("www.google.com", 80)
         if not ok then
             ngx.say("failed to connect to google: ", err)
             return
         end
         ngx.say("successfully connected to google!")
         sock:close()
     ';
 }

连接到 Unix Domain Socket 文件也是可能的：

 local sock = ngx.socket.tcp()
 local ok, err = sock:connect("unix:/tmp/memcached.sock")
 if not ok then
     ngx.say("failed to connect to the memcached unix domain socket: ", err)
     return
 end

假设 memcached （或其他服务）正在 Unix Domain Socket 文件 /tmp/memcached.sock 监听。

连接操作超时控制，是由 lua_socket_connect_timeout 配置指令和 settimeout 方法设置的。而后者有更高的优先级，例如：

 local sock = ngx.socket.tcp()
 sock:settimeout(1000)  -- one second timeout
 local ok, err = sock:connect(host, port)

调用这个方法 之前 调用 settimeout 方法设置超时时间，是非常重要的。

对已经连接状态的 socket 对象再次调用该方法，将导致原本的连接首先被关闭。

对于该方法的最后一个参数是个可选的 Lua 表，用来指定各种连接选项：

• pool 对即将被使用的连接池指定一个名字。如果没有指定该参数，连接池的名字将自动生成，使用 "<host>:<port>" 或 "<unix-socket-path>" 的命名方式。

支持可选的表参数，是在 v0.5.7 版本首次引入。

该特性在 v0.5.0rc1 版本首次引入。

返回目录

English source:

tcpsock:connect

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

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

context: rewrite_by_lua, access_by_lua*, content_by_lua*, ngx.timer.**

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 idle connections created by previous calls of this method (or the ngx.socket.connect function).

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 TCP server:

 location /test {
     resolver 8.8.8.8;

     content_by_lua '
         local sock = ngx.socket.tcp()
         local ok, err = sock:connect("www.google.com", 80)
         if not ok then
             ngx.say("failed to connect to google: ", err)
             return
         end
         ngx.say("successfully connected to google!")
         sock:close()
     ';
 }

Connecting to a Unix Domain Socket file is also possible:

 local sock = ngx.socket.tcp()
 local ok, err = sock:connect("unix:/tmp/memcached.sock")
 if not ok then
     ngx.say("failed to connect to the memcached unix domain socket: ", err)
     return
 end

assuming memcached (or something else) is listening on the unix domain socket file /tmp/memcached.sock.

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

 local sock = ngx.socket.tcp()
 sock:settimeout(1000)  -- one second timeout
 local ok, err = sock:connect(host, port)

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

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

An optional Lua table can be specified as the last argument to this method to specify various connect options:

• pool specify a custom name for the connection pool being used. If omitted, then the connection pool name will be generated from the string template "<host>:<port>" or "<unix-socket-path>".

The support for the options table argument was first introduced in the v0.5.7 release.

This method was first introduced in the v0.5.0rc1 release.

Back to TOC