Tell the truth about DNS in TLS module (#2643)

Purge the never-functional :dns() method, but document the DNS callback
in :on().

Fixes #2640

app/modules/tls.c

@@ -338,16 +338,7 @@ static int tls_socket_unhold( lua_State *L ) {
 
   return 0;
 }
-static int tls_socket_dns( lua_State *L ) {
-  tls_socket_ud *ud = (tls_socket_ud *)luaL_checkudata(L, 1, "tls.socket");
-  luaL_argcheck(L, ud, 1, "TLS socket expected");
-  if(ud==NULL){
-  	NODE_DBG("userdata is nil.\n");
-  	return 0;
-  }
 
-  return 0;
-}
 static int tls_socket_getpeer( lua_State *L ) {
   tls_socket_ud *ud = (tls_socket_ud *)luaL_checkudata(L, 1, "tls.socket");
   luaL_argcheck(L, ud, 1, "TLS socket expected");
@@ -629,7 +620,6 @@ static const LUA_REG_TYPE tls_socket_map[] = {
   { LSTRKEY( "send" ),    LFUNCVAL( tls_socket_send ) },
   { LSTRKEY( "hold" ),    LFUNCVAL( tls_socket_hold ) },
   { LSTRKEY( "unhold" ),  LFUNCVAL( tls_socket_unhold ) },
-  { LSTRKEY( "dns" ),     LFUNCVAL( tls_socket_dns ) },
   { LSTRKEY( "getpeer" ), LFUNCVAL( tls_socket_getpeer ) },
   { LSTRKEY( "__gc" ),    LFUNCVAL( tls_socket_delete ) },
   { LSTRKEY( "__index" ), LROVAL( tls_socket_map ) },

docs/modules/tls.md

@@ -109,27 +109,6 @@ Connect to a remote server.
 #### See also
 [`tls.socket:on()`](#tlssocketon)
 
-## tls.socket:dns()
-
-Provides DNS resolution for a hostname.
-
-#### Syntax
-`dns(domain, function(tls.socket, ip))`
-
-#### Parameters
-- `domain` domain name
-- `function(tls.socket, ip)` callback function. The first parameter is the socket, the second parameter is the IP address as a string.
-
-#### Returns
-`nil`
-
-#### Example
-```lua
-sk = tls.createConnection()
-sk:dns("google.com", function(conn, ip) print(ip) end)
-sk = nil
-```
-
 ## tls.socket:getpeer()
 
 Retrieve port and ip of peer.
@@ -168,10 +147,11 @@ Register callback functions for specific events.
 `on(event, function())`
 
 #### Parameters
-- `event` string, which can be "connection", "reconnection", "disconnection", "receive" or "sent"
+- `event` string, which can be "dns", "connection", "reconnection", "disconnection", "receive" or "sent"
 - `function(tls.socket[, string])` callback function. The first parameter is the socket.
 If event is "receive", the second parameter is the received data as string.
 If event is "reconnection", the second parameter is the reason of connection error (string).
+If event is "dns", the second parameter will be either `nil` or a string rendering of the resolved address.
 
 #### Returns
 `nil`