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

In the Apache HTTP Server API, the handler is a specific kind of hook responsible for generating the response. Examples of modules that include a handler are mod_proxy, mod_cgi, and mod_status.

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

-- example handler

require "string"

--[[
     This is the default method name for Lua handlers, see the optional
     function-name in the LuaMapHandler directive to choose a different
     entry point.
--]]
function handle(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 how modules (and Lua scripts) participate in the processing of requests. Each type of hook exposed by the server exists for a specific purposes such as mapping requests to the filesystem, performing access control, or setting mimetypes. General purpose hooks that simply run at handy times in the request lifecycle exist as well.

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 that rewrites the URI to a filesystem path.

require 'apache2'

function translate_name(r)
    if r.uri == "/translate-name" then
        r.filename = r.document_root .. "/find_me.txt"
        return apache2.OK
    end
    -- we don't care about this URL, give another module a chance
    return apache2.DECLINED
end

--[[ example hook that rewrites one URI to another URI. It returns a
     apache2.DECLINED to give other URL mappers a chance to work on the
     substitution, including the core translate_name hook which maps based
     on the DocumentRoot.

     Note: It is currently undefined as to whether this runs before or after
     mod_alias.
--]]

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	yes
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
handler	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
proxyreq	string	yes
range	string	no
subprocess_env	table	yes
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

apache2.PROXYREQ_NONE, apache2.PROXYREQ_PROXY, apache2.PROXYREQ_REVERSE, apache2.PROXYREQ_RESPONSE

internal constants used by mod_proxy

(Other HTTP status codes are not yet implemented.)