HomeSYNOPSIS
cgi
DESCRIPTION
For each http client request there is a request object. This object is passed to any lua code that is running on behalf of the request in the variable cgi.
The cgi object is a table structure that contains all information about the requests. It is split in three parts:
cgi = {
request = { ... },
header = { ... },
file = { ... },
query = { ... }, -- Only present when processing a GET or DELETE request with further data
post = { ... }, -- Only present when processing a POST, PUT or PATCH request
}
For all further descriptions of the structure, it is assumed as an example that the client has
requested the following URL:
http://example.test/sample/helloworld.lp
request
The fields request and file are very similar. While request describes the request itself, the field file describes the file that is currently being processed. Since the webserver supports server-side includes, it is possible that one client requests causes the processing of multiple files. In that case, for each file the field request stays the same, while the field file changes for each file in turn. While processing the top-level file for a request, the fields request and file contain basically the same information.
The request field contains information about the request itself:
| client_address | The IP address of the connected client, in string form. |
| client_port | The port number of the client connection. This is the port number of the client side of the connection. |
| scheme | Either "http" or "https". |
| method | The lower-cased request type, one of: "get", "post", "put", "patch", "delete". |
| urn |
The uniform resource name. This is the URI as passed by the client, but with the http://address removed. Example: "/sample/helloworld.lp" |
| script_file |
The plain filename of the request with all path information removed. Example: "helloworld.lp" |
| script_path |
The full internal path to the requested file, inside the web server's file system. Example: "/usr/lib/htdocs/sample/helloworld.lp" |
| script_pdir |
The internal directory path to the requested file, without the filename, inside the web server's file system. Example: "/usr/lib/htdocs/sample/" |
| script_vpath |
The path to the requested file, relative to the server root. Example: "/sample/helloworld.lp" |
| script_vdir |
The directory of the requested file, relative to the server root. Example: "/sample/" |
file
The file field contains information about the file that is currently being processed. Note that scripting on the server is able to nest files by including the contents of other files with server-side includes. When processing an included file, the field request always stays the same, while the field file reflects the file that is currently being processed.
As a second example, let's assume that the request has included the extra file common.lp.
The file field contains the fields:
| nesting_level |
A number that indicates how many levels of include nesting are currently present. For the top-level file,
the value is 0 and increments by one for each nesting. Example: 0 Example 2: 1 |
| urn |
The uniform resource name. Example: "/sample/helloworld.lp" Example 2: "common.lp" |
| script_file |
The plain filename of the file with all path information removed. Example: "helloworld.lp" Example 2: "common.lp" |
| script_path |
The full internal path to the requested file, inside the web server's file system. Example: "/usr/lib/htdocs/sample/helloworld.lp" Example 2: "/usr/lib/htdocs/sample/common.lp" |
| script_pdir |
The internal directory path to the requested file, without the filename, inside the web server's file system. Example: "/usr/lib/htdocs/sample/" Example 2: "/usr/lib/htdocs/sample/" |
| script_vpath |
The path to the requested file, relative to the server root. Example: "/sample/helloworld.lp" Example 2: "/sample/common.lp" |
| script_vdir |
The directory of the requested file, relative to the server root. Example: "/sample/" Example 2: "/sample/" |
header
The header field collects the information about the HTTP headers that the client sent. The list of fields is not fixed, but depends on the client. Common headers are:
- Accept-Encoding
- Accept-Language
- Accept
- Authorization
- Connection
- Host
- User-Agent
The header fields are stored into the table exactly as they where received from the client. More information about the HTTP header fields can be found at Wikipedia.
query
When the client has sent a get request with additional parameters, the values are collected into the query field of the cgi structure.
Suppose the client sent the request
http://example.test/sample/helloworld.lp?name=Alice&email=alice@bob%40test
then the query field would look like this:
query = {
name = "Alice",
email = "alice@bob.test",
}
As shown in the example, all percent-escaping is removed before putting the data into the table.
post
On post client request, the posted data is collected in the post field of the cgi structure.
The post field is structured a little more complicated that the query field since there can be additional information about each passed item.
Suppose the client sent a post request with the same information as above: a name field with the contents Alice and a email field with the contents alice@bob.test, then the post field would look like this:
post = {
name = {
value = "Alice",
},
email = {
value = "alice@bob.test",
},
}
In some cases the client has attached a length and/or a type to each data field. In that case there would be additional entries besides value with the names content_type and content_length.
This is an example when a file with the name uploaded.txt was uploaded by the client:
post = {
file = {
filename = "uploaded.txt",
content_type = "text/plain",
content_length = 12345,
},
}
In case of file uploads, then value field is not present if the file size is more that 4096 bytes. To get the file contents in that case use the additional functions cgi:getData(), cgi:saveData() or cgi:installData(). This is done in order to avoid copying data unnecessarily.