socket

​
Talk to custom protocols using asynchronous TCP sockets
For UDP sockets see hs.socket.udp​
hs.socket is implemented with CocoaAsyncSocket. CocoaAsyncSocket's tagging features provide a handy way to implement custom protocols.
For example, you can easily implement a basic HTTP client as follows (though using hs.http is recommended for the real world):
1
local TAG_HTTP_HEADER, TAG_HTTP_CONTENT = 1, 2
2
local body = ""
3
local function httpCallback(data, tag)
4
  if tag == TAG_HTTP_HEADER then
5
    print(tag, "TAG_HTTP_HEADER"); print(data)
6
    local contentLength = data:match("\r\nContent%-Length: (%d+)\r\n")
7
    client:read(tonumber(contentLength), TAG_HTTP_CONTENT)
8
  elseif tag == TAG_HTTP_CONTENT then
9
    print(tag, "TAG_HTTP_CONTENT"); print(data)
10
    body = data
11
  end
12
end
13
​
14
client = hs.socket.new(httpCallback):connect("google.com", 80)
15
client:write("GET /index.html HTTP/1.0\r\nHost: google.com\r\n\r\n")
16
client:read("\r\n\r\n", TAG_HTTP_HEADER)
Copied!
Resulting in the following console output (adjust log verbosity with hs.socket.setLogLevel()) :
1
            LuaSkin: (secondary thread): TCP socket connected
2
            LuaSkin: (secondary thread): Data written to TCP socket
3
            LuaSkin: (secondary thread): Data read from TCP socket
4
1 TAG_HTTP_HEADER
5
HTTP/1.0 301 Moved Permanently
6
Location: http://www.google.com/index.html
7
Content-Type: text/html; charset=UTF-8
8
Date: Thu, 03 Mar 2016 08:38:02 GMT
9
Expires: Sat, 02 Apr 2016 08:38:02 GMT
10
Cache-Control: public, max-age=2592000
11
Server: gws
12
Content-Length: 229
13
X-XSS-Protection: 1; mode=block
14
X-Frame-Options: SAMEORIGIN
15
​
16
            LuaSkin: (secondary thread): Data read from TCP socket
17
2 TAG_HTTP_CONTENT
18
<HTML><HEAD><meta http-equiv="content-type" content="text/html;charset=utf-8">
19
<TITLE>301 Moved</TITLE></HEAD><BODY>
20
<H1>301 Moved</H1>
21
The document has moved
22
<A HREF="http://www.google.com/index.html">here</A>.
23
</BODY></HTML>
24
            LuaSkin: (secondary thread): TCP socket disconnected Socket closed by remote peer
Copied!
Submodules
​hs.socket.udp​
API Overview
Variables - Configurable values
​timeout​
Functions - API calls offered directly by the extension
​parseAddress​
Constructors - API calls which return an object, typically one that offers API methods
​new​
​server​
Methods - API calls which can only be made on an object returned by a constructor
​connect​
​connected​
​connections​
​disconnect​
​info​
​listen​
​read​
​receive​
​send​
​setCallback​
​setTimeout​
​startTLS​
​write​
API Documentation
Variables
​timeout​
Signature
hs.socket.timeout
Type
Variable
Description
Timeout for the socket operations, in seconds. New hs.socket objects will be created with this timeout value, but can individually change it with the setTimeout method
Functions
​parseAddress​
Signature
hs.socket.parseAddress(sockaddr) -> table or nil
Type
Function
Description
Parses a binary socket address structure into a readable table
Parameters
sockaddr - A binary socket address structure, usually obtained from the info method or in hs.socket.udp's read callback​
Returns
A table describing the address with the following keys or nil:
host - A string containing the host IP
port - A number containing the port
addressFamily - A number containing the address family
Notes
Some address family definitions from <sys/socket.h>:
Constructors
​new​
Signature
hs.socket.new([fn]) -> hs.socket object
Type
Constructor
Description
Creates an unconnected asynchronous TCP socket object
Parameters
fn - An optional callback function for reading data from the socket, settable here for convenience
Returns
An hs.socket object
​server​
| Signature | hs.socket.server(port|path[, fn]) -> hs.socket object | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Constructor | | Description | Creates and binds an hs.socket instance to a port or path (Unix domain socket) for listening | | Parameters |
port - A port number [0-65535]. Ports [1-1023] are privileged. Port 0 allows the OS to select any available port
path - A string containing the path to the Unix domain socket
fn - An optional callback function for reading data from the socket, settable here for convenience
| | Returns |
An hs.socket object
|
Methods
​connect​
| Signature | hs.socket:connect({host, port}|path[, fn]) -> self or nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Connects an unconnected hs.socket instance | | Parameters |
host - A string containing the hostname or IP address
port - A port number [1-65535]
path - A string containing the path to the Unix domain socket
fn - An optional single-use callback function to execute after establishing the connection. Receives no parameters
| | Returns |
The hs.socket object or nil if an error occurred
| | Notes |
Either a host/port pair OR a Unix domain socket path must be supplied. If no port is passed, the first param is assumed to be a path to the socket file
|
​connected​
Signature
hs.socket:connected() -> bool
Type
Method
Description
Returns the connection status of the hs.socket instance
Parameters
None
Returns
true if connected, otherwise false
​connections​
Signature
hs.socket:connections() -> number
Type
Method
Description
Returns the number of connections to the socket, which is at most 1 for default (non-listening) sockets
Parameters
None
Returns
The number of connections to the socket
​disconnect​
Signature
hs.socket:disconnect() -> self
Type
Method
Description
Disconnects the hs.socket instance, freeing it for reuse
Parameters
None
Returns
The hs.socket object
Notes
If called on a listening socket with multiple connections, each client is disconnected
​info​
Signature
hs.socket:info() -> table
Type
Method
Description
Returns information on the hs.socket instance
Parameters
None
Returns
A table containing the following keys:
connectedAddress - string (sockaddr struct)
connectedHost - string
connectedPort - number
connectedURL - string
connections - number
isConnected - boolean
isDisconnected - boolean
isIPv4 - boolean
isIPv4Enabled - boolean
isIPv4PreferredOverIPv6 - boolean
isIPv6 - boolean
isIPv6Enabled - boolean
isSecure - boolean
localAddress - string (sockaddr struct)
localHost - string
localPort - number
timeout - number
unixSocketPath - string
userData - string
​listen​
| Signature | hs.socket:listen(port|path) -> self or nil | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Method | | Description | Binds an unconnected hs.socket instance to a port or path (Unix domain socket) for listening | | Parameters |
port - A port number [0-65535]. Ports [1-1023] are privileged. Port 0 allows the OS to select any available port
path - A string containing the path to the Unix domain socket
| | Returns |
The hs.socket object or nil if an error occurred
|
​read​
Signature
hs.socket:read(delimiter[, tag]) -> self or nil
Type
Method
Description
Read data from the socket. Results are passed to the callback function, which must be set to use this method
Parameters
delimiter - Either a number of bytes to read, or a string delimiter such as "\n" or "\r\n". Data is read up to and including the delimiter
tag - An optional integer to assist with labeling reads. It is passed to the callback to assist with implementing state machines for processing complex protocols
Returns
The hs.socket object or nil if an error occured
Notes
If called on a listening socket with multiple connections, data is read from each of them
​receive​
Signature
hs.socket:receive(delimiter[, tag]) -> self
Type
Method
Description
Alias for hs.socket:read​
​send​
Signature
hs.socket:send(message[, tag]) -> self
Type
Method
Description
Alias for hs.socket:write​
​setCallback​
Signature
hs.socket:setCallback([fn]) -> self
Type
Method
Description
Sets the read callback for the hs.socket instance. Must be set to read data from the socket
Parameters
fn - An optional callback function to process data read from the socket. nil or no argument clears the callback
Returns
The hs.socket object
​setTimeout​
Signature
hs.socket:setTimeout(timeout) -> self
Type
Method
Description
Sets the timeout for the socket operations. If the timeout value is negative, the operations will not use a timeout, which is the default
Parameters
timeout - A number containing the timeout duration, in seconds
Returns
The hs.socket object
​startTLS​
Signature
hs.socket:startTLS([verify][, peerName]) -> self
Type
Method
Description
Secures the socket with TLS. The socket will disconnect immediately if TLS negotiation fails
Parameters
verify - An optional boolean that, if false, allows TLS handshaking with servers with self-signed certificates and does not evaluate the chain of trust. Defaults to true and omitted if peerName is supplied
peerName - An optional string containing the fully qualified domain name of the peer to validate against — for example, store.apple.com. It should match the name in the X.509 certificate given by the remote party. See notes below
Returns
The hs.socket object
Notes
IMPORTANT SECURITY NOTE:The default settings will check to make sure the remote party's certificate is signed by atrusted 3rd party certificate agency (e.g. verisign) and that the certificate is not expired.However it will not verify the name on the certificate unless yougive it a name to verify against via peerName.The security implications of this are important to understand.Imagine you are attempting to create a secure connection to MySecureServer.com,but your socket gets directed to MaliciousServer.com because of a hacked DNS server.If you simply use the default settings, and MaliciousServer.com has a valid certificate,the default settings will not detect any problems since the certificate is valid.To properly secure your connection in this particular scenario youshould set peerName to "MySecureServer.com".
​write​
Signature
hs.socket:write(message[, tag][, fn]) -> self
Type
Method
Description
Write data to the socket
Parameters
message - A string containing data to be sent on the socket
tag - An optional integer to assist with labeling writes
fn - An optional single-use callback function to execute after writing data to the socket. Receives the tag parameter
Returns
The hs.socket object
Notes
If called on a listening socket with multiple connections, data is broadcasted to all connected sockets