== Kraken 8.01.0 ==

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.


  == Installation ==

After untar the tarball, change the current directory to the
installation one and run:

  make
  make test

If everthing is ok, turns to root and run:

  make install


  == Using it ==

The script must be a Lua script and the application is a Lua coroutine.

You don't need Lua installed to use Kraken, but you do to compile it!

Kraken is a standalone program. But if you set the package.path and the
package.cpath to find your Lua modules, you can use'em.

You can do it by editing /etc/kraken.lua.

The functions you must know are:

* kraken.registerApplication(coroutine) REQUIRED

  It registers the application to be used. The parameter must be a
  coroutine. The function of that must receive one parameter: the client
  socket for each connection.

* kraken.registerAddress {host=string, port=number} REQUIRED

  It register the address to listen. The parameter must be a table with
  two key-value pairs:
    host (string) = the IP
    port (number) = the port

* kraken.registerUser(number) NOT REQUIRED

  You can set Kraken to use another user by registering its UID. The
  parameter is a number representing the UID.

* kraken.socket() NOT REQUIRED

  You can use this function to create a new master socket. It returns
  a new socket or nil and a error message.


  == Kraken does not use LuaSocket! ==

As a standalone program, Kraken doesn't use LuaSocket, so it has its own
socket implementation.

The KrakenSocket offers the following methods:

  * server_socket:accept()

  Accepts new conections. It returns the client socket and a table
  representing the remote address.

  In case of faile, returns nil and a error message.

  * master_socket:bind {host=string, port=number}

  Binds a address to the socket. It receives as parameter a table
  accurately equals to the one of kraken.registerAddress().

  * socket:close()

  Closes the socket.

  * socket:getsockopt(number)

  Returns the socket options with ID received as parameter. It returns
  true or false.

  * socket:gettimeout()

  Returns the timeout for the socket. The first return is the receive
  timeout and then seconde is a table with receive and send ones.

  In case of faile, returns nil and a error message.

  * server_socket:listen([number])

  Sets the queue limit for incoming connections. Without parameter, the
  value is set as 1.

  * socket:rawrecv(number)

  Receives a string from connection. The number parameters represents
  the string length expected. It returns the string. This is a raw
  (low-level) method.

  * socket:rawsend(number or string)

  Sends a string to connection. If the paremeter is a number, is sent a
  character with ASCII code supplied. It returns true or false. This is
  a raw (low-level) method.

  * socket:receive()

  Receives a string from connection. It expects the string to be
  ended by line-feed (\n). It returns the string.

  * socket:send(string)

  Sends a string to connection. The parameter is the string to send.
  It returns true or false.

  * socket:setsockopt(number, boolean)

  Sets a socket option. The first parameter is the option ID and the
  second one is true (set) or false (unset).

  * socket:settimeout(number)

  Sets the socket timeout as the supplied number.

The option IDs can be found from the table kraken.SO.


Good luck!

http://luaforge.net/projects/wsgi/
http://luawsgi.blogspot.com/

Rodrigo Cacilhas <cacilhas@maisideias.com.br>