| @@ -0,0 +1,408 @@
+{{{
+#!rst
+==============
+a power-magnet
+==============
+
+------------------
+Module: mod_magnet
+------------------
+
+
+
+.. contents:: Table of Contents
+
+Requirements
+============
+
+:Version: lighttpd 1.4.12 and higher
+:Packages: lua >= 5.0
+
+Overview
+========
+
+mod_magnet is a module to control the request handling in lighty.
+
+.. note::
+
+ Currently this page only describes the final syntax and some part might not work with the current svn-code.
+
+.. note::
+
+ Keep in mind that the magnet is executed in the core of lighty. EVERY long-running operation is blocking
+ ALL connections in the server. You are warned. For time-consuming or blocking scripts use mod_fastcgi and friends.
+
+For performance reasons mod_magnet caches the compiled script. For each script-run the script itself is checked for
+freshness and recompile if neccesary.
+
+
+Installation
+============
+
+mod_magnet needs a lighty which is compiled with the lua-support (--with-lua). Lua 5.0 or higher are required by
+the module. ::
+
+ server.modules = ( ..., "mod_magnet", ... )
+
+Options
+=======
+
+mod_magnet can attract a request in several stages in the request-handling.
+
+* either at the same level as mod_rewrite, before any parsing of the URL is done
+* or at a later stage, when the doc-root is known and the physical-path is already setup
+
+It depends on the purpose of the script which stage you want to intercept. Usually you want to use
+the 2nd stage where the physical-path which relates to your request is known. At this level you
+can run checks against lighty.env["physical.path"].
+
+::
+
+ magnet.attract-raw-url-to = ...
+ magnet.attract-physical-path-to = ...
+
+
+Tables
+======
+
+Most of the interaction between between mod_magnet and lighty is done through tables. Tables in lua are hashes (Perl), dictionaries (Java), arrays (PHP), ...
+
+Request-Environment
+-------------------
+
+Lighttpd has its internal variables which are exported as read/write to the magnet.
+
+If "http://example.org/search.php?q=lighty" is requested this results in a request like ::
+
+ GET /search.php?q=lighty HTTP/1.1
+ Host: example.org
+
+When you are using ``attract-raw-url-to`` you can access the following variables:
+
+* parts of the request-line
+
+ * lighty.env["request.uri"] = "/search.php?q=lighty"
+
+* HTTP request-headers
+
+ * lighty.request["Host"] = "example.org"
+
+Later in the request-handling, the URL is splitted, cleaned up and turned into a physical path name:
+
+* parts of the URI
+
+ * lighty.env["uri.path"] = "/search.php"
+ * lighty.env["uri.path-raw"] = "/search.php"
+ * lighty.env["uri.scheme"] = "http"
+ * lighty.env["uri.authority"] = "example.org"
+ * lighty.env["uri.query"] = "q=lighty"
+
+* filenames, pathnames
+
+ * lighty.env["physical.path"] = "/my-docroot/search.php"
+ * lighty.env["physical.rel-path"] = "/search.php"
+ * lighty.env["physical.doc-root"] = "/my-docroot"
+
+All of them are readable, not all of the are writable (or don't have an effect if you write to them).
+
+As a start, you might want to use those variables for writing: ::
+
+ -- 1. simple rewriting is done via the request.uri
+ lighty.env["request.uri"] = ...
+ return lighty.RESTART_REQUEST
+
+ -- 2. changing the physical-path
+ lighty.env["physical.path"] = ...
+
+ -- 3. changing the query-string
+ lighty.env["uri.query"] = ...
+
+Response Headers
+----------------
+
+If you want to set a response header for your request, you can add a field to the lighty.header[] table: ::
+
+ lighty.header["Content-Type"] = "text/html"
+
+Sending Content
+===============
+
+You can generate your own content and send it out to the clients. ::
+
+ lighty.content = { "<pre>", { filename = "/etc/passwd" }, "</pre>" }
+ lighty.header["Content-Type"] = "text/html"
+
+ return 200
+
+The lighty.content[] table is executed when the script is finished. The elements of the array are processed left to right and the elements can either be a string or a table. Strings are included AS IS into the output of the request.
+
+* Strings
+
+ * are included as is
+
+* Tables
+
+ * filename = "<absolute-path>" is required
+ * offset = <number> [default: 0]
+ * length = <number> [default: size of the file - offset]
+
+Internally lighty will use the sendfile() call to send out the static files at full speed.
+
+Status Codes
+============
+
+You might have seen it already in other examples: In case you are handling the request completly in the magnet you
+can return your own status-codes. Examples are: Redirected, Input Validation, ... ::
+
+ if (lighty.env["uri.scheme"] == "http") then
+ lighty.header["Location"] = "https://" .. lighty.env["uri.authority"] .. lighty.env["request.uri"]
+ return 302
+ end
+
+You every number above and equal to 100 is taken as final status code and finishes the request. No other modules are
+executed after this return.
+
+A special return-code is lighty.RESTART_REQUEST (currently equal to 99) which is usually used in combination with
+changing the request.uri in a rewrite. It restarts the splitting of the request-uri again.
+
+If you return nothing (or nil) the request-handling just continues.
+
+Debugging
+=========
+
+To easy debugging we overloaded the print()-function in lua and redirect the output of print() to the error-log. ::
+
+ print("Host: " .. lighty.request["Host"])
+ print("Request-URI: " .. lighty.env["request.uri"])
+
+
+Examples
+========
+
+Sending text-files as HTML
+--------------------------
+
+This is a bit simplistic, but it illustrates the idea: Take a text-file and cover it in a <pre> tag.
+
+Config-file ::
+
+ magnet.attract-physical-path-to = server.docroot + "/readme.lua"
+
+readme.lua ::
+
+ lighty.content = { "<pre>", { filename = "/README" }, "</pre>" }
+ lighty.header["Content-Type"] = "text/html"
+
+ return 200
+
+Maintainance pages
+------------------
|
