WSAPI
Lua Web Server API

Overview

WSAPI includes a set of helper libraries to make writing applications and web frameworks easier. To use these libraries just require them in your application or framework.

Request

wsapi.request.new(wsapi_env, [options]) - creates a new request object wrapping wsapi_env; options is an (optional) table of extra options for the request; the delay_post option tells wsapi.request to not process POST data on creation, the overwrite option tells WSAPI to overwrite input parameters with the same name instead of collecting them in a list, and the mk_app option passes the mk application that created the request object, used in some of the methods

req:parse_post() - processed the POST data in case the processing was delayed by passing delay_post = true on creation of the request

req:qd_encode(tab) - encodes tab as a query string

req:route_link(route, tab, ...) - creates a link to mk route route, encoding tab as the query string and passing extra arguments to the link builder of the route

req:link_<route>(tab, ...) - same as req:route_link(route, tab, ...)

req:link(uri, tab) - makes an internal application link to the specified resource uri, with tab encoded as a query string. For example, if the app is addressed by /foo/bar.lua then req:link("/baz", { id = 2 }) returns "/foo/bar.lua/baz?id=2"

req:static_link(uri, tab) - as req:link, but builds a link external to the application. In the previous example it would return "/foo/baz?id=2"

req:absolute_link(url, tab) - just encodes tab as a query string and appends it to url. Use it to make non-decorated links

req:empty(s) - returns true if s is nil or a blank string, false otherwise

req:empty_param(name) - same as req:empty(req.params[name])

req.GET - table with GET parameters of request

req.POST - table with POST parameters of request

req.method - request method (usually "GET" or "POST")

req.path_info - PATH_INFO metavariable

req.script_name - SCRIPT_NAME metavariable

req.doc_root - DOCUMENT_ROOT metavariable

req.env - the original WSAPI environment

req.app_path - the path of the WSAPI application currently running

req.query_string - unparsed query string

req.params - union of req.GET and req.POST, built on demand

req.cookies[name] - gets value of a cookie from browser

Response

wsapi.response.new([status, headers]) - creates a new response object, optionally setting an initial status code and header table. If a Content-Type was not passed in the initial header table then sets it as "text/html". The default status code is 200

res.status - status code to be returned to server

res.headers - table with headers to be returned to server

res:content_type(mime) - sets the Content-Type header to mime

res:write(...) - adds the arguments to the body, flattening an argument if it is a table

res:set_cookie(name, value) - sets the value of a cookie, value can be either a string or a table with fields value, expires (expiration date), domain, path, and secure. All fields except value are optional

res:delete_cookie(name, path) - tells the browser to erase a cookie, with an optional path

res:delete_cookie(name, path) - tells the browser to erase a cookie, with an optional path and domain

res:redirect(url) - sets status and headers for a redirect response to url, and returns a WSAPI response that does the redirect

res:forward(uri) - sets the PATH_INFO metavariable to uri (if not nil) and returns a mk FORWARD response to tell mk to keep trying to find a request handler

res:finish() - finishes response, returning status, headers and an iterator for the body

Util

wsapi.util.url_encode(s) - encodes s according to RFC2396

wsapi.util.url_decode(s) - decodes s according to RFC2396

wsapi.util.sanitize(text) - sanitizes all HTML tags in text, replacing < and > with the corresponding entity codes

wsapi.util.not_empty(s) - returns true if s is not nil or the empty string

wsapi.util.getopt(arg, options) - POSIX style command line argument parser, arg contains the command line arguments in a standard table, options is a string with the letters that expect string values. Returns a table with the options that have been passed and their values

wsapi.util.make_env_get(qs) - makes a mock WSAPI environment with GET method and qs as the query string

wsapi.util.make_env_post(pd, type, qs) - makes a mock WSAPI environment with POST method and pd as the postdata, type as the encoding (x-www-form-urlenconded default), and qs as the query string

wsapi.util.make_rewindable(wsapi_env) - wraps wsapi_env in a new environment that lets you process the POST data more than once. This new environment's input object has a rewind method that you can call to allow you to read the POST data again.

Mock

make_handler(wsapi_app) - Creates a mock handler for testing the WSAPI application you pass in.

The resulting handler will be a table with three fields:

app - The app itself.

get - A function to perform GET requests.

post - A function to perform POST requests.

The get and post functions both accept the following arguments:

path (required) - The path to request. Do not include the query string, this is specified in params.

params (optional) - A table of query or form data parameters.

headers (optional) - Any request headers you wish to specify.

Valid XHTML 1.0!