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 purpose, such as mapping requests to the file system,
performing access control, or setting mime types:
| Quick handler |
LuaQuickHandler |
This is the first hook that will be called after a request has
been mapped to a host or virtual host |
| Translate name |
LuaHookTranslateName |
This phase translates the requested URI into a filename on the
system. Modules such as mod_alias and
mod_rewrite operate in this phase. |
| Map to storage |
LuaHookMapToStorage |
This phase maps files to their physical, cached or external/proxied storage.
It can be used by proxy or caching modules |
| Check Access |
LuaHookAccessChecker |
This phase checks whether a client has access to a resource. This
phase is run before the user is authenticated, so beware.
|
| Check User ID |
LuaHookCheckUserID |
This phase it used to check the negotiated user ID |
| Check Authorization |
LuaHookAuthChecker or
LuaAuthzProvider |
This phase authorizes a user based on the negotiated credentials, such as
user ID, client certificate etc.
|
| Check Type |
LuaHookTypeChecker |
This phase checks the requested file and assigns a content type and
a handler to it |
| Fixups |
LuaHookFixups |
This is the final "fix anything" phase before the content handlers
are run. Any last-minute changes to the request should be made here. |
| Content handler |
fx. .lua files or through LuaMapHandler |
This is where the content is handled. Files are read, parsed, some are run,
and the result is sent to the client |
| Logging |
LuaHookLog |
Once a request has been handled, it enters several logging phases,
which logs the request in either the error or access log. Mod_lua
is able to hook into the start of this and control logging output. |
Hook functions are passed the request object as their only argument
(except for LuaAuthzProvider, which also gets passed the arguments from
the Require directive).
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.
translate_name.lua
-- 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
translate_name2.lua
--[[ 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: Use the early/late flags in the directive to make it run 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
