Kraken

Introduction

Kraken is a simple dispatcher that allows the programmers develop their own network servers with no need thinking about socket problems.

Kraken is the low-level part of the LuaWsgi Project, but it can be used apart.

Portuguese speakers can refer to LuaWsgi Changelog for more informations.

Use

The kraken binary works pretty like lua51 binary, but with a little difference: it automatically imports (require) the kraken module, with its own socket support.

Kraken does not work with LuaSocket!!!

Functions

The kraken module offers four functions:

1. kraken.registerApplication(application_coroutine) – receives a thread (coroutine) and registers it as the Lua state to process the connections.
   The function of the thread must have two arguments: the first receives the client socket and the second receives a table with two keys:
   • host the remote address
   • port the remote port
2. kraken.registerAddress(address_table) – receives a table representing the server socket, i.e., the address and the port to listen.
   The table must be two keys:
   • host the local address("*" for all)
   • port the local port to listen
3. kraken.registerUser(uid) – receives the uid of the user who must run the application.
   This function is optional.
4. kraken.socket(domain, type, protocol) – returns a master socket. The three parameters are:
   • domain: the socket domain, default: socket.AF.INET
   • type: the socket type, default: socket.SOCK.STREAM
   • protocol: the protocol, default: 0
   This function is optional.

Tables

• kraken.AF – List of socket domains. See socket manpage 2.
  For example: AF_INET as kraken.AF.INET.
• kraken.SO – List of socket options. See socket manpage 7.
  For example: SO_REUSEADDR as kraken.SO.REUSEADDR.
• kraken.SOCK – List of socket types. See socket manpage 2.
  For example: SOCK_STREAM as kraken.SOCK.STREAM.

Socket object

The object returned by the kraken.socket() has some useful methods.

• socket:accept() – waits for connections. Returns the client socket to the connection and a table representing the remote peer, with the keys:
  • host the remote address
  • port the remote port
• socket:bind { host = host, port = port } – binds a socket to an local address, making the socket a server one. If The host is "*", the address will be 0.0.0.0 (ANY_ADDR).
• socket:close() – closes the socket.
• socket:getoption(option) – returns if the option is set (see the kraken.SO table).
• socket:gettimeout() – returns a table with the receive (rcvtimeo key) and send (sndtimeo key) timeouts in seconds.
• socket:listen(backlog) – sets the queue limit for incomming connections.
• socket:rawrecv(length) – receives length bytes of arbitrary string. This function works closely like the C function recv().
• socket:rawsend(data) – sends the data arbitrary string. If data is a unsigned number less than 256, it sends one byte with the data value. This function works closely like the C Function send().
• socket:receive() – receives one line of regular string without line terminator.
• socket:send() – sends one line of regular string, adding the cflf line terminator.
• socket:setoption(option, bool) – sets a socket option (see the kraken.SO table).
• socket:settimeout(timeout) – sets the socket timeout (in seconds).

Example

local app = coroutine.create(function (skt, addr)
	print("Connection from " .. addr.host .. ":" .. addr.port)
	skt:rawsend "> "
	print("Received: " .. skt:receive())
	skt:send("Ok\n")
end)

assert(kraken.registerApplication(app))
assert(kraken.registerAddress { host = "*", port =  8001 })
assert(kraken.loop())

Rodrigo Cacilhas