Introduction - Core4 Lua Event System

OVERVIEW

The httpd module implements a basic HTTP web server.

The built-in web server is coupled with the Lua system so the full programming ability of Lua is available for serving web pages.

In addition to the applications own web pages, there is a secondary server root directory at /lib/htdocs. This is provided by the SDK and contains pages for remote system configuration, update and debug. The service homepage of the device is reachable at http://xx.xx.xx.xx/settings/. The service home page can be password protected or filtered. [TODO: How?]

Apart from serving static files, there are three ways to mix HTML with scripting:

file.shtml
Server parsed HTML

Files ending in .shtml are parsed by the server before they are sent to the client.

: Includes the contents of the file into the output. If the filename is an absolute path starting with '/', the path is made relative to the server root directory. If the filename is a relative path, it is seen relative to the directory of the file that contains the include directive.

file.lp
Lua Page

Files ending in .lp are parsed by the server before they are sent to the client. These files allow server-side includes as above, but they also allow included Lua code.

<?lua commands ?>: Runs the given commands. Anything written by the commands is merged into the output at the place where the commands had been. Alternatively the syntax <% commands %> can be used.
<?lua= expression ?>: This markup processes expression in the same way as print() would. The output is inserted at the place where the expression had been. Alternatively the syntax <%= expression %> can be used.

file.lua
Lua Script

Files ending in .lua are processed by the Lua interpreter like any other Lua program. They run in the same environment as the underlying event loop. They have access to all global variables.

Lua commands and expressions inside a Lua Page (.lp) or a Lua Script (.lua) always have access to two predefined variables:

httpd: The base instance of the web server running the request.
cgi: A table with information about the current request.

Lua scripting can write output to the page using cgi:write(). Do not use print(). The print() command sends its output to stdout as usual, and not to the web page.

QUICK START

To include a web server into an event driven application, instantiate it like this:

httpd = http.new(app, "/usr/lib/htdocs") httpd:listen(80)

This will provide access to the web pages stored below the path /usr/lib/htdocs. This path is called the server root. The server will not allow access to files outside the directory.

Please note that the web server responds only as long as the main event loop is running.

COMMANDS

List of global commands

http.new(): Create a new HTTP server

List of server commands

httpd:close(): Close the server.
httpd:listen(): Start or stop taking client request.
httpd:setMaxMemory(): Configure the maximum memory used by the server.
httpd:setPath(): Sets the server root directory.
httpd:setSystemPath(): Sets the secondary server root directory.

List of request commands

cgi:authenticate(): Perform basic authentication.
cgi:close(): Close the request.
cgi:contentheader(): Send a HTTP header.
cgi:cookie(): Set a cookie on the client.
cgi:dofile(): Nested file inclusion.
cgi:error(): Send a HTTP error header.
cgi:getData(): Get data attached to a post request.
cgi:header(): Send a HTTP header line.
cgi:htmlheader(): Send a complete HTTP header indicating that the data is of the type text/html.
cgi:index(): Send a fancy directory listing.
cgi:installData(): Perform system firmware update with data from a post request.
cgi:mkurlpath(): Combine a path and some parameters into a well formed URL.
cgi:redirect(): Send a HTTP 302 redirect header.
cgi:saveData(): Save data from a post request to a file.
cgi:tohtml(): Convert a string into HTML-safe format.
cgi:write(): Send data to the client.