Kraken

Kraken

Introduction

Kraken is a simple dispatcher that allows the programmers to 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.

Kraken was tested only on GNU/Linux, but we want it to work on many (or any) Posix systems.

See also: Kraken Socket.

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:

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

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

kraken.registerUser(uid) – receives the UID of the user who must run the application.

This function is optional.

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.

kraken.mm – This table is useful for memory management and must be set only in configuration file (/etc/kraken.lua). The keys are:

tries number of attempts to fork when there's no available memory.
timeout time between two attempts to fork: if it's a number, it's the maximum time in milliseconds; if it's a table, the first value's the minimum and the second one's the maximum, both in milliseconds.

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 a 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 whether the option is set or not (see the kraken.SO table).

socket:getip() – returns the IP if there's one bound.

socket:getport() – returns the port if there's one bound.

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 CRLF 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