Apache Module mod_lua

Basic Configuration

The basic module loading directive is

mod_lua provides a handler named lua-script, which can be used with an AddHandler directive:

This will cause mod_lua to handle requests for files ending in .lua by invoking that file's handle function.

For more flexibility, see LuaMapHandler.

Writing Handlers

mod_lua always looks to invoke a function for the handler, rather than just evaluating a script body CGI style. A handler function looks something like this:

-- example handler

require "string"

function handle_something(r)
    r.content_type = "text/plain"
    r:puts("Hello Lua World!\n")

    if r.method == 'GET' then
        for k, v in pairs( r:parseargs() ) do
            r:puts( string.format("%s: %s", k, v) )
        end
    elseif r.method == 'POST' then
        for k, v in pairs( r:parsebody() ) do
            r:puts( string.format("%s: %s", k, v) )
        end
    else
        r:puts("unknown HTTP method " .. r.method)
    end 
end

This handler function just prints out the uri or form encoded arguments to a plaintext page.

This means (and in fact encourages) that you can have multiple handlers (or hooks, or filters) in the same script.

Writing Hooks

Hook functions are passed the request object as their only argument. They can return any value, depending on the hook, but most commonly they'll return OK, DONE, or DECLINED, which you can write in lua as apache2.OK, apache2.DONE, or apache2.DECLINED, or else an HTTP status code.

-- example hook

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.uri = "/find_me.txt"
        return apache2.DECLINED
    end
    return apache2.DECLINED
end

Data Structures

request_rec

The request_rec is mapped in as a userdata. It has a metatable which lets you do useful things with it. For the most part it has the same fields as the request_rec struct (see httpd.h until we get better docs here) many of which are writeable as well as readable. (The table fields' content can be changed, but the fields themselves cannot be set to different tables.)

Name	Lua type	Writable
ap_auth_type	string	no
args	string	no
assbackwards	boolean	no
canonical_filename	string	no
content_encoding	string	no
content_type	string	yes
document_root	string	no
err_headers_out	table	no
filename	string	yes
headers_in	table	yes
headers_out	table	yes
hostname	string	no
method	string	no
notes	table	yes
path_info	string	no
protocol	string	no
range	string	no
status	number	yes
the_request	string	no
unparsed_uri	string	no
uri	string	yes
user	string	yes

The request_rec has (at least) the following methods:

r:addoutputfilter(name|function) -- add an output filter

r:parseargs() -- returns a lua table containing the request's query string arguments

r:parsebody() -- parse the request body as a POST and return a lua table

r:puts("hello", " world", "!") -- print to response body

r:write("a single string") -- print to response body

Logging Functions

apache2 Package

A package named apache2 is available with (at least) the following contents.

apache2.OK

internal constant OK. Handlers should return this if they've handled the request.

apache2.DECLINED

internal constant DECLINED. Handlers should return this if they are not going to handle the request.

apache2.DONE

internal constant DONE.

apache2.version

Apache HTTP server version string

apache2.HTTP_MOVED_TEMPORARILY

HTTP status code

(Other HTTP status codes are not yet implemented.)