You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by br...@apache.org on 2007/05/01 21:58:45 UTC
svn commit: r534218 - in /httpd/mod_wombat/trunk: NOTICE README docs/
docs/README docs/basic-configuration.txt docs/building-from-subversion.txt
docs/running-developer-tests.txt docs/writing-handlers.txt sample_httpd.conf
Author: brianm
Date: Tue May 1 12:58:44 2007
New Revision: 534218
URL: http://svn.apache.org/viewvc?view=rev&rev=534218
Log:
add information on building, running tests, and re-organize the README into some actual documentation
Added:
httpd/mod_wombat/trunk/docs/
httpd/mod_wombat/trunk/docs/README
httpd/mod_wombat/trunk/docs/basic-configuration.txt
httpd/mod_wombat/trunk/docs/building-from-subversion.txt
httpd/mod_wombat/trunk/docs/running-developer-tests.txt
httpd/mod_wombat/trunk/docs/writing-handlers.txt
Modified:
httpd/mod_wombat/trunk/NOTICE
httpd/mod_wombat/trunk/README
httpd/mod_wombat/trunk/sample_httpd.conf
Modified: httpd/mod_wombat/trunk/NOTICE
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/NOTICE?view=diff&rev=534218&r1=534217&r2=534218
==============================================================================
--- httpd/mod_wombat/trunk/NOTICE (original)
+++ httpd/mod_wombat/trunk/NOTICE Tue May 1 12:58:44 2007
@@ -8,6 +8,3 @@
developed by Copyright 1994-2006 Lua.org, PUC-Rio.
Lua is distributed under the MIT license
( http://www.lua.org/license.html ).
-
-
-
Modified: httpd/mod_wombat/trunk/README
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/README?view=diff&rev=534218&r1=534217&r2=534218
==============================================================================
--- httpd/mod_wombat/trunk/README (original)
+++ httpd/mod_wombat/trunk/README Tue May 1 12:58:44 2007
@@ -1,233 +1,24 @@
Requirements:
lua 5.1 ( http://www.lua.org/ )
- Yes, it uses 5.1 not 5.0
-
libapreq2 ( http://httpd.apache.org/apreq/download.cgi )
- For reasons of temporary annoyance with autoconf you
- *must* specify a prefix when building libapreq2, a la
- ./configure --prefix=/usr/local/libapreq2 \
- --with-apache2-apxs=/usr/localapache2/bin/apxs
-
- apache 2.X ( http://httpd.apache.org/ )
- Any MPM is okay (this means threaded workers such as
- worker and event work fine)
-
-Building:
- Basic Steps:
- svn co https://svn.i-want-a-pony.com/repos/wombat/trunk wombat
- cd wombat
- ./bootstrap
- ./configure --with-apxs=/path/to/apache2/bin/apxs \
- --with-apreq2=/path/to/libapreq2
- make
- sudo make install
-
- Notes:
- The bootstrap script may report an error that it cannot find
- libtoolize or glibtoolize. That is fine as long as it
- doesn't report that it cannot find both of them. The script
- just sets up the autoconf magic.
-
- If you have lua installed in a non-standard location
- the configure script accepts a --with-lua as well.
-
- If compiling (make) reports an error that it cannot find the
- libapreq2 header file, please tell me ( brianm@apache.org )
- as this occurs under some configurations but we haven't
- hammered down the weird things libapreq2 does with its
- install. If you build libapreq2 with a --prefix configuration
- option, it always seems to work.
-
-Configuration:
- See sample_httpd.conf for examples
-
- The basic module loading directive is
- LoadModule apreq_module modules/mod_apreq2.so
- LoadModule wombat_module modules/mod_wombat.so
- I included the apreq_module in the example as you need it to :-)
-
- The handler name is "lua-script" so you can use the normal
- AddHandler directive, such as "AddHandler lua-script .lua" to
- set anything ending in .lua to use mod_wombat to evaluate
-
- mod_wombat exports several additional directives:
-
- LuaRoot /path/to/a/directory
- Specify the base path which will be used to evaluate all
- relative paths within mod_wombat. If not specified they
- will be resolved relative to the current working directory,
- which may not always work well for a server.
-
- LuaConfig /path/to/config_file.lua function_name
- Allows for configuring mod_lua directly in Lua, which is
- kind of convenient.
-
- MapLuaHandler uri-pattern /path/to/lua/script.lua [function-name]
- This directive matches a uri pattern to invoke a specific
- handler function in a specific file. It uses PCRE regular
- expressions to match the uri, and supports interpolating
- match groups into both the file path and the function name
- be careful writing your regular expressions to avoid security
- issues.
-
- Examples:
- MapLuaHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
- This would match uri's such as /photos/show?id=9
- to the file /scripts/photos.lua and invoke the
- handler function handle_show on the lua vm after
- loading that file.
-
- MapLuaHandler /bingo /scripts/wombat.lua
- This would invoke the "handle" function, which
- is the default if no specific function name is
- provided.
-
- LuaPackagePath /path/to/include/?.lua
- Add a path to lua's module search path. Follows the same
- conventions as lua (ie, can do shared libraries, etc).
- This just munges the package.path in the lua vms.
-
- Examples:
- LuaPackagePath /scripts/lib/?.lua
- LuaPackagePath /scripts/lib/?/init.lua
- LuaPackagePath /scripts/lib/?.so
-
- LuaCodeCache stat|forever|never
- Specify the behavior of the in-memory code cache. The default
- is stat, which stats the top level script (not any included
- ones) each time that file is needed, and reloads it if the
- modified time indicates it is newer than the one it has
- already loaded. The other values cause it to keep the file
- cached forever (don't stat and replace) or to never cache the
- file.
-
- In general stat or forever is good production and stat or never
- for deveopment.
-
- Examples:
- LuaCodeCache stat
- LuaCodeCache forever
- LuaCodeCache never
-
- LuaHookTranslateName /path/to/lua/script.lua hook_function_name
- Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
- request processing. The hook function receives a single
- argument, the request_rec, and should return a status code,
- which is either an HTTP error code, or the constants defined
- in the apache2 module: apache2.OK, apache2.DECLINED, or
- apache2.DONE.
-
- For those new to hooks, basically each hook will be invoked
- until one of them returns apache2.OK. If your hook doesn't
- want to do the translation it should just return
- apache2.DECLINED. If the request should stop processing, then
- return apache2.DONE.
-
- Example:
- LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
-
- -- /scripts/conf/hooks.lua --
- function silly_mapper(r)
- if r.uri == "/" then
- r.file = "/var/www/home.lua"
- return apache2.OK
- else
- return apache2.DECLINED
- end
- end
-
- LuaHookFixups /path/to/lua/script.lua hook_function_name
- Just like LuaHookTranslateName, but executed at the fixups phase
-
- LuaHookMapToStorage /path/to/lua/script.lua hook_function_name
- ...
+ Apache HTTPD 2.2 ( http://httpd.apache.org/ )
- LuaHookCheckUserID /path/to/lua/script.lua hook_function_name
- ...
-
- LuaHookTypeChecker /path/to/lua/script.lua hook_function_name
- ...
-
- LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
- ...
-
- LuaHookAccessChecker /path/to/lua/script.lua hook_function_name
- ...
-
- LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
- ...
+Building:
+ For now, see docs/building-from-subversion.txt
- LuaHookInsertFilter /path/to/lua/script.lua hook_function_name
- Not Yet Implemented
-
-Writing Lua Handlers:
- mod_wombat 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.lua --
- require "string"
+TODO:
+ Vastly improve writing-handlers.txt
- 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
+ Add docs on configuring via the LuaConfig directive
- 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.
-
-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, and has (at least) the following methods:
-
- r:puts("hello", " world", "!") -- print to response body
-
- -- logging functions
- r:debug("This is a debug log message")
- r:info("This is an info log message")
- r:notice("This is an notice log message")
- r:warn("This is an warn log message")
- r:err("This is an err log message")
- r:alert("This is an alert log message")
- r:crit("This is an crit log message")
- r:emerg("This is an emerg log message")
-
-Running Tests:
- Yeah, kind of dodgy right now if you aren't on a Mac-like filesystem
- layout, have the username brianm, and so on. I'll clean it up soon,
- I promise!
-
- Running the tests requires LuaSocket
- http://www.cs.princeton.edu/~diego/professional/luasocket/
-
-TODO:
+ Add docs for arbitrary hooks
+ Probably a specific authz tutorial as well
Provide means to get useful output from lua errors in response body
Probably have to put it on the vm spec for pre-handler
errors, as it is pre-handler, will prolly be on the request_config
somewhere, but sometimes cannot put there, so... fun
-
- LuaHookInsertFilter
-
+
Filters
Mapping in the server_rec
@@ -253,9 +44,9 @@
To subscribe send email to dev-subscribe@httpd.apache.org
Note that this is for development discussion, not user support :-)
-Developers:
- Brian McCallister (CLA on file)
- Paul Querna (CLA on file)
- Garrett Rooney (CLA on file)
- Martin Traverso (CLA on file)
+Contributors Include:
+ Brian McCallister
+ Paul Querna
+ Garrett Rooney
+ Martin Traverso
Added: httpd/mod_wombat/trunk/docs/README
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/docs/README?view=auto&rev=534218
==============================================================================
--- httpd/mod_wombat/trunk/docs/README (added)
+++ httpd/mod_wombat/trunk/docs/README Tue May 1 12:58:44 2007
@@ -0,0 +1,12 @@
+Index of documents:
+ building-from-subversion.txt
+ Basic build instructions
+
+ basic-configuration.txt
+ Getting mod_wombat up and running
+
+ running-developer-tests.txt
+ How to set up and run the developer and regression tests
+
+ writing-handlers.txt
+ basics on writing handlers in mod_wombat
\ No newline at end of file
Added: httpd/mod_wombat/trunk/docs/basic-configuration.txt
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/docs/basic-configuration.txt?view=auto&rev=534218
==============================================================================
--- httpd/mod_wombat/trunk/docs/basic-configuration.txt (added)
+++ httpd/mod_wombat/trunk/docs/basic-configuration.txt Tue May 1 12:58:44 2007
@@ -0,0 +1,125 @@
+See sample_httpd.conf for examples
+
+The basic module loading directive is
+ LoadModule apreq_module modules/mod_apreq2.so
+ LoadModule wombat_module modules/mod_wombat.so
+I included the apreq_module in the example as you need it to :-)
+
+The handler name is "lua-script" so you can use the normal
+AddHandler directive, such as "AddHandler lua-script .lua" to
+set anything ending in .lua to use mod_wombat to evaluate
+
+mod_wombat exports several additional directives:
+
+ LuaRoot /path/to/a/directory
+ Specify the base path which will be used to evaluate all
+ relative paths within mod_wombat. If not specified they
+ will be resolved relative to the current working directory,
+ which may not always work well for a server.
+
+ LuaConfig /path/to/config_file.lua function_name
+ Allows for configuring mod_lua directly in Lua, which is
+ kind of convenient.
+
+ Configuring mod_lua this way actually exposes a much more
+ powerful set of configuration options, and is strongly
+ encouraged.
+
+ MapLuaHandler uri-pattern /path/to/lua/script.lua [function-name]
+ This directive matches a uri pattern to invoke a specific
+ handler function in a specific file. It uses PCRE regular
+ expressions to match the uri, and supports interpolating
+ match groups into both the file path and the function name
+ be careful writing your regular expressions to avoid security
+ issues.
+
+ Examples:
+ MapLuaHandler /(\w+)/(/w+) /scripts/$1.lua handle_$2
+ This would match uri's such as /photos/show?id=9
+ to the file /scripts/photos.lua and invoke the
+ handler function handle_show on the lua vm after
+ loading that file.
+
+ MapLuaHandler /bingo /scripts/wombat.lua
+ This would invoke the "handle" function, which
+ is the default if no specific function name is
+ provided.
+
+ LuaPackagePath /path/to/include/?.lua
+ Add a path to lua's module search path. Follows the same
+ conventions as lua (ie, can do shared libraries, etc).
+ This just munges the package.path in the lua vms.
+
+ Examples:
+ LuaPackagePath /scripts/lib/?.lua
+ LuaPackagePath /scripts/lib/?/init.lua
+ LuaPackagePath /scripts/lib/?.so
+
+ LuaCodeCache stat|forever|never
+ Specify the behavior of the in-memory code cache. The default
+ is stat, which stats the top level script (not any included
+ ones) each time that file is needed, and reloads it if the
+ modified time indicates it is newer than the one it has
+ already loaded. The other values cause it to keep the file
+ cached forever (don't stat and replace) or to never cache the
+ file.
+
+ In general stat or forever is good production and stat or never
+ for deveopment.
+
+ Examples:
+ LuaCodeCache stat
+ LuaCodeCache forever
+ LuaCodeCache never
+
+ LuaHookTranslateName /path/to/lua/script.lua hook_function_name
+ Add a hook (at APR_HOOK_MIDDLE) to the translate name phase of
+ request processing. The hook function receives a single
+ argument, the request_rec, and should return a status code,
+ which is either an HTTP error code, or the constants defined
+ in the apache2 module: apache2.OK, apache2.DECLINED, or
+ apache2.DONE.
+
+ For those new to hooks, basically each hook will be invoked
+ until one of them returns apache2.OK. If your hook doesn't
+ want to do the translation it should just return
+ apache2.DECLINED. If the request should stop processing, then
+ return apache2.DONE.
+
+ Example:
+ LuaHookTranslateName /scripts/conf/hooks.lua silly_mapper
+
+ -- /scripts/conf/hooks.lua --
+ function silly_mapper(r)
+ if r.uri == "/" then
+ r.file = "/var/www/home.lua"
+ return apache2.OK
+ else
+ return apache2.DECLINED
+ end
+ end
+
+ LuaHookFixups /path/to/lua/script.lua hook_function_name
+ Just like LuaHookTranslateName, but executed at the fixups phase
+
+ LuaHookMapToStorage /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookCheckUserID /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookTypeChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookAccessChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookAuthChecker /path/to/lua/script.lua hook_function_name
+ ...
+
+ LuaHookInsertFilter /path/to/lua/script.lua hook_function_name
+ Not Yet Implemented
+
Added: httpd/mod_wombat/trunk/docs/building-from-subversion.txt
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/docs/building-from-subversion.txt?view=auto&rev=534218
==============================================================================
--- httpd/mod_wombat/trunk/docs/building-from-subversion.txt (added)
+++ httpd/mod_wombat/trunk/docs/building-from-subversion.txt Tue May 1 12:58:44 2007
@@ -0,0 +1,72 @@
+Install Lua 5.1
+ http://www.lua.org/download.html
+
+ Lua does not use autoconf for compiling. This means that you do not use
+ ./configure. It has good build instructions, though, so hopefully things
+ will go smoothly.
+
+ I like to change the directory Lua installs to. In order to do this you
+ need to set LUA_TOP in the configuration makefile for Lua. For these
+ instructions I have set LUA_TOP to /Users/brianm/.opt/lua-5.1.2 -- you
+ will see this directory referred to later.
+
+
+Install Apache HTTPD 2.2
+ http://httpd.apache.org/download.cgi
+
+ You can build apache pretty much any way you like, as long as you enable
+ dynamic module loading (--enable-so) so that mod_wombat can be loaded.
+
+ You may user (and I encourage you to!) the threaded MPMs -- mod_wombat
+ plays nicely with them.
+
+ I build it with these flags:
+
+ ./configure --prefix=/Users/brianm/.opt/httpd-2.2.4-worker-wombat \
+ --with-mpm=worker \
+ --enable-so
+
+
+Install libapreq2
+ http://httpd.apache.org/apreq/download.cgi
+ The download link is in the page body, NOT under the "Download!" link
+ in the left hand column.
+
+ Right now, mod_wombat requires libapreq2 for parsing entity bodies. This
+ dependency will probably be made optional in the near future, but for now
+ you need it.
+
+ I build it with these flags:
+
+ ./configure --prefix=/Users/brianm/.opt/libapreq2-2.0.8 \
+ --with-apache2-apxs=/Users/brianm/.opt/httpd-2.2.4-worker-wombat/bin/apxs
+
+
+Install mod_wombat from subversion
+ http://svn.apache.org/repos/asf/httpd/mod_wombat/trunk
+
+ The first step, when building from subversion, is to bootstrap autoconf.
+ To do this run the bootstrap script:
+
+ ./bootstrap
+
+ The bootstrap script may report an error that it cannot find
+ libtoolize or glibtoolize. That is fine as long as it
+ doesn't report that it cannot find both of them. The script
+ just sets up the autoconf magic.
+
+ After that, it is a normal configure and build:
+
+ ./configure --with-lua=/Users/brianm/.opt/lua-5.1.2/ \
+ --with-apxs=/Users/brianm/.opt/httpd-2.2.4-worker-wombat/bin/apxs \
+ --with-apreq2=/Users/brianm/.opt/libapreq2-2.0.8/
+
+ If compiling (make) reports an error that it cannot find the
+ libapreq2 header file, please tell me ( brianm@apache.org )
+ as this occurs under some configurations but we haven't
+ hammered down the weird things libapreq2 does with its
+ install. If you build libapreq2 with a --prefix configuration
+ option, it always seems to work.
+
+
+That is it. To configure mod_wombat, look at the basic-configuration.txt document.
\ No newline at end of file
Added: httpd/mod_wombat/trunk/docs/running-developer-tests.txt
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/docs/running-developer-tests.txt?view=auto&rev=534218
==============================================================================
--- httpd/mod_wombat/trunk/docs/running-developer-tests.txt (added)
+++ httpd/mod_wombat/trunk/docs/running-developer-tests.txt Tue May 1 12:58:44 2007
@@ -0,0 +1,15 @@
+The first step is to build mod_wombat per the instructions in
+building-from-subversion.txt.
+
+Once built, replace apache's httpd.conf with test/test_httpd.conf
+ You will need to customize the directories listed in test_httpd.conf
+ to match your system.
+
+Build and install LuaSocket
+ http://www.cs.princeton.edu/~diego/professional/luasocket/
+
+
+
+Finally, to run the tests, start apache and run:
+ $ cd test
+ $ lua ./test.lua
Added: httpd/mod_wombat/trunk/docs/writing-handlers.txt
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/docs/writing-handlers.txt?view=auto&rev=534218
==============================================================================
--- httpd/mod_wombat/trunk/docs/writing-handlers.txt (added)
+++ httpd/mod_wombat/trunk/docs/writing-handlers.txt Tue May 1 12:58:44 2007
@@ -0,0 +1,49 @@
+mod_wombat 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.lua --
+ 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.
+
+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, and has (at least) the following methods:
+
+ r:puts("hello", " world", "!") -- print to response body
+
+ -- logging functions
+ r:debug("This is a debug log message")
+ r:info("This is an info log message")
+ r:notice("This is an notice log message")
+ r:warn("This is an warn log message")
+ r:err("This is an err log message")
+ r:alert("This is an alert log message")
+ r:crit("This is an crit log message")
+ r:emerg("This is an emerg log message")
Modified: httpd/mod_wombat/trunk/sample_httpd.conf
URL: http://svn.apache.org/viewvc/httpd/mod_wombat/trunk/sample_httpd.conf?view=diff&rev=534218&r1=534217&r2=534218
==============================================================================
--- httpd/mod_wombat/trunk/sample_httpd.conf (original)
+++ httpd/mod_wombat/trunk/sample_httpd.conf Tue May 1 12:58:44 2007
@@ -1,5 +1,5 @@
-ServerRoot "/opt/httpd-2.2.3"
-DocumentRoot "/opt/httpd-2.2.3/htdocs"
+ServerRoot "/opt/httpd-2.2.4"
+DocumentRoot "/opt/httpd-2.2.4/htdocs"
Listen 8000
LoadModule apreq_module modules/mod_apreq2.so