Introduction - Core4 Lua Event System

OVERVIEW

The httpd module implements a basic HTTP web server. Besides unencrypted connections it also supports TLS by means of mbed TLS.

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

Supported request types are GET, POST, PUT, PATCH and DELETE.

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/.

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. The included code has access to all global variables.

<?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 local variables:

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

Both of these variables are local to the running cgi script and lose their scope once the page has been delivered.

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.

The next example sets up a https (SSL/TLS encrypted) webserver. The example code uses a testing key-pair and server certificate. It does not check for errors while loading the key pair and certificate. At any error, the server will silently fail to start.

httpd = http.new(app, "/usr/lib/htdocs") httpd:loadKeyFile("/usr/lib/cert/test.key") httpd:loadCertFile("/usr/lib/cert/test.crt") httpd:secureListen(443)

It is possible to have the server respond to both encrypted and unencrypted connections by calling httpd:listen() and httpd:secureListen() together.

COMMANDS

List of global commands

http.new(): Create a new HTTP server
http.tohtml(): Convert a string into HTML-safe format.
http.mkurlpath(): Combine a path and some parameters into a well formed URL.

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.

List of server callbacks

httpd:request(): This callback is called for each client request, before it is processed. Can be used to do authentication.
httpd:finduser(): This callback is during basic authentication. It is used to retrieve the saved password for a certain user name.

Request handle

cgi: Description of the structure of a cgi request handle.
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/put/patch request.
cgi:addheader(): 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.