Button

WSAPI is now at Github, and also available through LuaRocks (luarocks install wsapi).

Overview

WSAPI is the base of Kepler and assumes three kinds of modules. Servers, Filters and Applications. Filters can act both as servers for applications or as applications for servers, thus working as middleware.

If you look at the current Kepler architecture you have something like:

  CGILua
----------
   SAPI
----------
Web Server

The same system using WSAPI could be seen as:

 CGILua
----------
 Filter 1
----------
 Filter 2
----------
  WSAPI
----------
Web Server

or

  Orbit
----------
 Filter 3
----------
 Filter 2
----------
  WSAPI
----------
Web Server

or even

Lua servlets
------------
   WSAPI
------------
 Web Server

Where the filters are seen as applications by the servers and as servers by the application. Orbit would be an application of the Filter 3 server and so on down to the WSAPI layer.

Examples of filters could be session handlers, loggers, URL manipulators etc. Filters can be reused by more than one framework, just as the example shows Filter 2 being used both by CGILua and Orbit.

Another use for filters is Rings itself. Instead of forcing Rings on either the server or the application, we could have a wsapi.ringer that envelopes an application on a Ring just like VEnv used to envelope a function. The wsapi.fcgi launcher uses this to isolate applications (while letting an application have persistent data). The wsapi.sapi application (CGILua) uses this to isolate CGILua requests.

Details

We offer an API very close in spirit to WSGI and Rack, consisting of a separation of server and application roles.

  • Servers can be of three types

    • Native: Xavante
    • Embedded: mod_lua, mod_wombat, ISAPI
    • Launched: CGI, FastCGI
  • The server calls an application passing an Environment. The application returns 3 values for the server:

    • the HTTP status code
    • a HTTP headers table
    • an iterator over the output
  • An environment is a table with the usual set of CGI Metavariables (as in RFC3875 and eventually data from a specific type of server.

  • The HTTP status code and headers are used in the response

  • The iterator is used by the server to consume the output from the application.

  • Other than the communication API itself, WSAPI also offers helper APIs to handle POST processing, Cookies, URLs and what more is needed. Most of this code was refactored from Orbit and CGILua.

If this works as planned, not only Kepler, Orbit or CGILua will benefit from WSAPI, but any other web solution using Lua can use WSAPI as its base layer. This can make things easier both for application developers and server implementations.

For example, a developer can use the FastCGI WSAPI server to implement a specific solution and then someone else could probably port this solution to Xavante, since it will also be WSAPI based.

Check Talk:WSAPI for a somewhat out of date discussion on this topic.