Rename mod_wombat -> mod_lua.

Note that this isn't a complete transformation yet, but it should basically compile and load as mod_lua.


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@728494 13f79535-47bb-0310-9956-ffa450edef68

modules/lua/docs/README

@@ -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

modules/lua/docs/basic-configuration.txt

@@ -0,0 +1,143 @@
+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.
+
+    LuaScope once|request|conn|server [max|min max]
+        Specify the lifecycle scope of the Lua interpreter which will
+        be used by handlers in this "Directory." The default is "once"
+        
+        once: use the interpreter once and throw it away.
+        
+        request: use the interpreter to handle anything based on 
+                 the same file within this request, which is also 
+                 request scoped.
+                 
+        conn: Same as request but attached to the connection_rec
+        
+        server: This one is different than others because the
+                server scope is quite long lived, and multiple threads
+                will have the same server_rec. To accommodate this
+                server scoped interpreter are stored in an apr
+                resource list. The min and max arguments are intended
+                to specify the pool size, but are unused at this time.
+
+    LuaMapHandler 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:
+            LuaMapHandler /(\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.
+                
+            LuaMapHandler /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. This just munges the package.path in the 
+        lua vms.
+        
+        Examples:
+            LuaPackagePath /scripts/lib/?.lua
+            LuaPackagePath /scripts/lib/?/init.lua
+
+    LuaPackageCPath /path/to/include/?.soa
+        Add a path to lua's shared library search path. Follows the same
+        conventions as lua. This just munges the package.cpath in the 
+        lua vms.
+        
+        Examples:
+            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
+ 

modules/lua/docs/building-from-subversion.txt

@@ -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.

modules/lua/docs/running-developer-tests.txt

@@ -0,0 +1,16 @@
+-*- mode:org -*-
+* Building mod_wombat
+  The first step is to build mod_wombat per the instructions in
+  building-from-subversion.txt.
+
+* Build and install LuaSocket
+    http://www.cs.princeton.edu/~diego/professional/luasocket/
+    FreeBSD: /usr/ports/net/luasocket
+
+* Running Tests
+  1. Replace apache's httpd.conf with test/test_httpd.conf
+  2. Customize the new httpd.conf to match your directories
+  3. Finally, to run the tests, start apache and run:
+     $ cd test
+     $ lua ./test.lua
+     FreeBSD: lua-5.1 ./test.lua

modules/lua/docs/writing-handlers.txt

@@ -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")