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.
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())
Space Home