httpd:request

This callback is called for each client request that is received. When called, the client request has been fully received. It is passed inside the cgi variable. No reply has been sent to the client yet.

Typically this callback is used to do basic authentication. With basic authentication, the browser asks the user for a user name and password in a pop-up dialog. For more information on how to do this see the description of the command cgi:authenticate().

Another use could be the management of client sessions. The callback implementation could check for a session cookie. If none is present it sets up a new session and sets the cookie with cgi:cookie(). If a cookie was sent by the client, the callback looks it up in a session cache and restores the session. In both cases, the session information can be stored into the variable cgi.session. Any further scripting called via a lua page (.lp) or lua script (.lua) file then has access to the session information.

The callback runs as a protected function (See pcall()). If there is a Lua exception while the callback runs, the webserver will send an error message to the client and end the request. The main Lua application will not exit.

Theoretically it is possible to handle each request completely in this callback. This is unusual and complicated though. It is possible by sending a header with cgi:header(), cgi:contentheader() or cgi:htmlheader(), followed by the response data using cgi:write(). A better way to process requests dynamically is using lua page (.lp) or lua script (.lua) files. See web server overview for more information.