From 4bfe4797dbd07610aa243e936e9ed0bf02c3b905 Mon Sep 17 00:00:00 2001 From: Daniel Gruno Date: Sun, 5 May 2013 08:04:21 +0000 Subject: [PATCH] Remove all the stuff that has been ported to mod_lua, and add an example load balancer. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1479253 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/developer/lua.xml | 1498 ++------------------------------- 1 file changed, 50 insertions(+), 1448 deletions(-) diff --git a/docs/manual/developer/lua.xml b/docs/manual/developer/lua.xml index 2d8a3405ca..c68f227549 100644 --- a/docs/manual/developer/lua.xml +++ b/docs/manual/developer/lua.xml @@ -512,1471 +512,73 @@ end -
Example 5: Overlays using LuaMapHandler + +
Example 5: A rudimentary load balancer

-Coming soon! + This is an example of how you can create a load balancing mechanism. + In this example, we will be setting/getting the number of requests served + by each backend using IVM variables, and preferring the backend with least + requests served in total:

-LuaMapHandler ^/portal/([a-z]+)/ /path/to/lua/script.lua handle_$1 +LuaHookTranslateName /path/to/script.lua proxy_handler -
- -
Example 6: Basic Lua scripts -

-Also coming soon -

-
- - - - - - -
-HTTPd bindings: String manipulation -

-apache2.base64_encode -
-apache2.base64_decode -
-apache2.escape -
-apache2.unescape -
-apache2.escapehtml -
-apache2.md5 -
-apache2.sha1 -
-apache2.os_escape_path -
-apache2.escape_logitem -
-

-
-apache2.base64_decode( - request_rec<em> r</em>,  string<em> string</em> - ) - -

-Decodes a base64-encoded string -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
stringThe string to decode
-

-Return value(s): -
-The base64-decoded string. -

-

-Example: -

- -local str = "This is a test" -local encoded = apache2.base64_encode(str) -local decoded = apache2.base64_decode(encoded) - -

 

-
-
-apache2.base64_encode( - request_rec<em> r</em>,  string<em> string</em> - ) - -

-Encodes a string using the base64 encoding scheme. -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
stringThe string to encode
-

-Example: -

- -local str = "This is a test" -local encoded = apache2.base64_encode(str) -local decoded = apache2.base64_decode(encoded) - -

 

-
-
-apache2.escape( - request_rec<em> r</em>,  string<em> string</em> - ) - -

-url-escapes a string -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
stringThe string to escape
-

-Return value(s): -
-The URL-escaped string. -

-

-Example: -

- -local str = "This is a test" -local escaped = apache2.escape(str) -print(escaped) -- prints "This+is+a+test" - -

 

-
-
-apache2.escape_logitem( - request_rec<em> r</em>,  string<em> path</em> - ) - -

-Escape a string for logging -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
pathThe string to escape
-

-Return value(s): -
-The converted string -

-

 

-
-
-apache2.escapehtml( - request_rec<em> r</em>,  string<em> html</em>,  boolean<em> toasc</em> - ) - -

-Escapes HTML entities. -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
htmlThe HTML code to escape
toascWhether to escape all non-ASCI characters as &#nnn;
-

-Return value(s): -
-The escaped HTML code. -

-

-Example: -

- -local html = "<b>Testing!</b>" -local escaped = apache2.escapehtml(html) -r:puts(escaped) -- prints "&lt;b&gt;Testing!&lt;/b&gt;" - -

 

-
-
-apache2.md5( - request_rec<em> r</em>,  string<em> string</em> - ) - -

-Computes an MD5 digest sum based on a string (binary safe) -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
stringThe (binary) string to digest
-

-Return value(s): -
-The MD5 digest sum of the data provided -

-

-Example: -

- -local text = "The quick brown fox jumps over the lazy dog" -local md5 = apache2.md51(text) -r:puts(md5) -- prints out "9e107d9d372bb6826bd81d3542a419d6" - -

 

-
-
-apache2.os_escape_path( - request_rec<em> r</em>,  string<em> path</em>,  boolean<em> partial</em> - ) - -

-convert an OS path to a URL in an OS dependent way. -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
pathThe path to convert
partialpartial if set, assume that the path will be appended to something with a '/' in it (and thus does not prefix "./")
-

-Return value(s): -
-The converted URL -

-

-Example: -

- -local path = ap_os_escape_path("C:/foo/bar.txt") - -

 

-
-
-apache2.sha1( - request_rec<em> r</em>,  string<em> string</em> - ) - -

-Computes an SHA-1 digest sum based on a string (binary safe) -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
stringThe (binary) string to digest
-

-Return value(s): -
-The SHA-1 digest sum of the data provided -

-

-Example: -

- -local text = "The quick brown fox jumps over the lazy dog" -local sha1 = apache2.sha1(text) -r:puts(sha1) -- prints out "2fd4e1c67a2d28fced849ee1bb76e7391b93eb12" - -

 

-
-
-apache2.unescape( - request_rec<em> r</em>,  string<em> string</em> - ) - -

-unescapes an URL-escaped string -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
stringThe string to unescape
-

-Return value(s): -
-The URL-unescaped string -

-

-Example: -

-local str = "This+is+a+test" -local unescaped = apache2.unescape(str) -print(unescaped) -- prints "This is a test" - -

 

-
-
+--[[ + This script uses a basic IVM table to determine where to + send the request. +]]-- -
-HTTPd bindings: Request handling -

-apache2.requestbody -
-apache2.add_input_filter -
-apache2.get_basic_auth_pw -
-apache2.set_document_root -
-apache2.set_context_prefix -
-apache2.get_server_name_for_url -
-apache2.set_keepalive -
-apache2.make_etag -
-apache2.send_interim_response -
-

-
-apache2.add_input_filter( - request_rec<em> r</em>,  string<em> filter</em> - ) - -

-Adds an input filter to the request -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
filterThe name of the filter handler to add
-

-Example: -

- -apache2.add_input_filter(r, "SPAM_FILTER") -- Check input for spam..? - -

 

-
-
-apache2.get_basic_auth_pw( - request_rec<em> r</em> - ) - -

-Returns the password from a basic authorization request or nil if none was supplied -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-The password from a basic authorization request or nil if none was supplied -

-

 

-
-
-apache2.get_server_name_for_url( - request_rec<em> r</em> - ) - -

-Get the current server name from the request for the purposes of using in a URL. -If the server name is an IPv6 literal address, it will be returned in URL format (e.g., "[fe80::1]"). -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

 

-
-
-apache2.make_etag( - request_rec<em> r</em>,  boolean<em> force_weak</em> - ) - -

-Constructs an entity tag from the resource information. If it's a real file, build in some of the file characteristics. -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
force_weakforce_weak Force the entity tag to be weak - it could be modified again in as short an interval.
-

-Return value(s): -
-The entity tag -

-

 

-
-
-apache2.requestbody( - request_rec<em> r</em>,  number<em> size</em>,  string<em> filename</em> - ) - -

-Reads the request body. If a filename is specified, the request body will be written to that file and the number of bytes written returned, otherwise, the full request body will be returned as a string. -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
sizeThe maximum size allowed, or 0/nil for unlimited size
filenameThe file to save the output to, or nil to return it as a string
-

-Return value(s): -
-The number of bytes written if a filename was specified, otherwise it returns the entire request body as a string. -

-

-Example: -

- -if tonumber(r.headers_in['Content-Length'] or 0) < 10000 then - local smallfile = apache2.requestbody(r, 10000) -- fetch a small file into memory - r:puts("I saved the uploaded file in memory") -else - local read = apache2.requestbody(r, 0, "/path/to/tmp") - r:puts("I saved the uploaded file in a temp directory. Total bytes written was: ", read) -end - -

 

-
-
-apache2.send_interim_response( - request_rec<em> r</em>,  boolean<em> send_headers</em> - ) - -

-Sends an interim (HTTP 1xx) response immediately. -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
send_headerssend_headers Whether to send&clear headers in r->headers_out
-

-Example: -

- -apache2.send_interim_response(r, false) - -

 

-
-
-apache2.set_context_prefix( - request_rec<em> r</em>,  string<em> prefix</em>,  string<em> document</em> - ) - -

-Set context_prefix and context_document_root for a request. -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
prefixThe URI prefix, without trailing slash
documentThe corresponding directory on disk, without trailing slash
-

 

-
-
-apache2.set_document_root( - request_rec<em> r</em>,  string<em> root</em> - ) - -

-Sets the document root of the request. -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
rootroot
-

-Example: -

- --- Suppose our real document root is /var/bar, then... -if r.hostname == "www.foo.com" then - apache2.set_document_root(r, "/www/foo") -- change document root on the fly -end - -

 

-
-
-apache2.set_keepalive( - request_rec<em> r</em> - ) - -

-Sets the keepalive status for this request -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Return value(s): -
-True if keepalive can be set, false otherwise -

-

 

-
-
+local backends = { + “http://backend1.foo.com/“, + “http://backend2.foo.com/“, + “http://backend3.foo.com/“ +} -
-HTTPd bindings: Parser functions -

-apache2.expr -
-apache2.regex -
-apache2.strcmp_match -
-

-
-apache2.expr( - request_rec<em> r</em>,  string<em> expression</em> - ) - -

-Evaluates an ap_expr (think <If ...>) expression and returns true if the expression is true, false otherwise. A second value containing an error string is returned if the expression is invalid. -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
expressionexpression
-

-Return value(s): -
-True if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string. -

-

-Example: -

- -if apache2.expr("%{REQUEST_URI} =~ /force-gzip") then - r:addoutputfilter("DEFLATE") -end - -

 

-
-
-apache2.regex( - request_rec<em> r</em>,  string<em> expression</em>,  string<em> source</em> - ) - -

-Evaluates a regular expression and, if it matches the source string, captures the variables and returns the matches as a table. On error, it returns nil. -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
expressionexpression to match for
sourcethe source string to capture from
-

-Return value(s): -
-True if the expression evaluates as true, false if the expression doesn't evaluate as true or if an error occurred. If an error occurred during parsing, a second value will be returned, containng the error string. -

-

-Example: -

- -local matches = apache2.regex(r, [[(\S+) kitty]], "Hello kitty") -if matches and matches[1] then - r:puts("You said ", matches[1], " to kitty") -end - -

 

-
-
-apache2.strcmp_match( - string<em> str</em>,  string<em> expexted</em>,  boolean<em> ignoreCase</em> - ) - -

-Determines if a string matches a pattern containing the wildcards '?' or '*' -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
strThe string to check
expextedThe pattern to match against
ignoreCaseWhether to ignore case when matching
-

-Return value(s): -
-True if the two strings match, false otherwise. -

-

-Example: -

- -if apache2.strcmp_match("foo.bar", "foo.*") then - r:puts("It matches!") +function pick_backend(r) + local chosen_backend = 1 -- default to backend1 + local lowest_count = nil + for i = 1, #backends, 1 do -- Loop through all backends + local count = r:ivm_get("proxy_request_count_" .. i) + if not count then -- If this backend hasn't been used at all, prefer it + chosen_backend = i + lowest_count = 0 + break + end + if not lowest_count or lowest_count > count then -- If this backend has had less requests, pick it for now + chosen_backend = i + lowest_count = count + end + end + lowest_count = lowest_count + 1 + r:ivm_set("proxy_request_count_" .. chosen_backend, lowest_count) + return chosen_backend end - -

 

-
-
-
-HTTPd bindings: Server settings -

-apache2.add_version_component -
-apache2.mpm_query -
-apache2.terminate -
-apache2.scoreboard_process -
-apache2.scoreboard_worker -
-apache2.module_info -
-apache2.loaded_modules -
-apache2.runtime_dir_relative -
-apache2.server_info -
-apache2.state_query -
-apache2.custom_response -
-apache2.exists_config_define -
-

-
-apache2.add_version_component( - request_rec<em> r</em>,  string<em> component</em> - ) - -

-Adds a component to the server description and banner strings -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
componentThe component to add
-

-Example: -

- -if not apache2.banner():match("FooModule") then -- Make sure we haven't added it already - apache2.add_version_component(r, "FooModule/1.0") -end - -

 

-
-
-apache2.custom_response( - request_rec<em> r</em>,  number<em> status</em>,  string<em> string</em> - ) - -

-Install a custom response handler for a given status -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
statusThe status for which the custom response should be used
stringThe custom response. This can be a static string, a file or a URL
-

-Example: -

- -apache2.custom_response(r, 404, "Not found!!") - -

 

-
-
-apache2.exists_config_define( - string<em> name</em> - ) - -

-Checks for a definition from the server command line -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
nameThe define to check for
-

-Example: -

- -if apache2.exists_config_define("FOO") then - r:puts("This server was started with -DFOO") -end - -

 

-
-
-apache2.loaded_modules( - - ) - -

-Returns a table containing the name (c filename) of all loaded modules -

-

-Arguments: -

-

None

-

-Return value(s): -
-A table containing the name (c filename) of all loaded modules -

-

 

-
-
-apache2.module_info( - string<em> c</em>,  string<em> file</em> - ) - -

-Returns information about a specific module (if loaded) -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
cc
filefile
-

-Return value(s): -
-The various commands available to this module as a table, or nil if the module wasn't found. -

-

 

-
-
-apache2.mpm_query( - number<em> i</em> - ) - -

-Queries the MPM for a specific value -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
ii
-

-Return value(s): -
-The queried value -

-

 

-
-
-apache2.runtime_dir_relative( - request_rec<em> r</em>,  string<em> file</em> - ) - -

-Returns the path of a file relative to the default runtime directory -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
filefile
-

-Return value(s): -
-The path of a file relative to the default runtime directory -

-

 

-
-
-apache2.scoreboard_process( - request_rec<em> r</em>,  number<em> child</em> - ) - -

-Returns the scoreboard for a server daemon as a table -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
childThe server child to query
-

-Return value(s): -
-The scoreboard for a server daemon as a table -

-

 

-
-
-apache2.scoreboard_worker( - request_rec<em> r</em>,  number<em> child</em>,  number<em> thread</em> - ) - -

-Returns the scoreboard for a single thread as a table -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
childThe server child to query
threadThe thread to query
-

-Return value(s): -
-The scoreboard for a single thread as a table -

-

 

-
-
-apache2.server_info( - - ) - -

-Returns a table with information about the server program -

-

-Arguments: -

-

None

-

-Return value(s): -
-A table with information about the server program -

-

 

-
-
-apache2.state_query( - number<em> field</em> - ) - -

-Query the server for some state information -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
fieldWhich information is requested
-

-Example: -

- -local gen = apache2.state_query(2) -r:puts("This is generation no. " .. gen .. " of the top-level parent") - -

 

-
-
-apache2.terminate( - - ) - -

-Kills off a server process. This has no other use than to show how dangerous mod_lua can be ;) -

-

-Arguments: -

-

None

-

 

-
-
-
-HTTPd bindings: Database connectivity -

-apache2.dbopen -
-db:query -
-db:do -
-db:close -
-

-
-apache2.dbopen( - request_rec<em> r</em>,  string<em> dbtype</em>,  string<em> conn_string</em> - ) - -

-Opens up a new database connection. See the DB functions for mod_pLua for more info on this. -

-

-Arguments: -

- - - - - - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
dbtypedbtype
conn_stringconnection string
-

-Return value(s): -
-The database connection as a table with functions, or nil if the connection failed. If a connection failed, a second argument (string) with the error code is returned. -

-

-Example: -

- -local db, error = apache2.dbopen(r, "mod_dbd") -if error then - r:puts("DB error: ", error) -else - -- DB stuff here +function proxy_handler(r) + local backend = pick_backend(r) -- Pick a backend based on no. of requests served + r.handler = "proxy-server" + r.proxyreq = apache2.PROXYREQ_REVERSE + r.filename = "proxy:" .. backends[backend] .. r.uri + return apache2.DECLINED -- let the proxy handler do this instead end - -

 

-
-
-db:close( - request_rec<em> r</em> - ) - -

-Closes a database connection -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
-

-Example: -

- -local db = apache2.dbopen(r, "mod_dbd") -- open a db connection -db:close() -- close it down - -

 

-
-
-db:do( - request_rec<em> r</em>,  string<em> query</em> - ) - -

-Executes a statement that doesn't return a result set -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
queryThe SQL statement to execute
-

-Return value(s): -
-If the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message. -

-

-Example: -

- -local db = apache2.dbopen(r, "mod_dbd") -local affected = db:do("DELETE FROM `table` WHERE 1") -if affected then - r:puts("Affected ", affected, " rows") -end - -

 

-
-
-db:query( - request_rec<em> r</em>,  string<em> query</em> - ) - -

-Queries the database for information using the specified statement. -

-

-Arguments: -

- - - - - - - - - - - - - -
ArgumentDescription
rThe mod_lua request handle
queryThe SQL statement to execute
-

-Return value(s): -
-If the statement is valid, a table of results are returned. If an error occurred, the first return value is false and the second return value is a string containing an error message. -

-

-Example: -

- -local db = apache2.dbopen(r, "mod_dbd") -local result, error = db:query("SELECT * FROM `table` WHERE 1") -if result then - for key, value in pairs(result) - r:puts( ("row %s: %s\n"):format(key, table.concat(value, ", ")) ) - end -end - -

 

-
+
-
-HTTPd bindings: Miscellaneous -

-apache2.clock -
-apache2.sleep -
-

-
-apache2.clock( - - ) - -

-Returns the current time in microseconds. -

+ +
Example 6: Overlays using LuaMapHandler

-Arguments: +Coming soon!

-

None

-

-Return value(s): -
-The current time in microseconds. -

-

 

+ +LuaMapHandler ^/portal/([a-z]+)/ /path/to/lua/script.lua handle_$1 +
-
-apache2.sleep( - number<em> seconds</em> - ) - -

-Sleeps for a while. Floating point values can be used to sleep for less than a second. -

-

-Arguments: -

- - - - - - - - - -
ArgumentDescription
secondsThe number of seconds to sleep.
+ +
Example 6: Basic Lua scripts

-Example: +Also coming soon

- -r:puts("this is ") -apache2.flush(r) -apache2.sleep(0.25) -- sleep for a quarter second. -r:puts("delayed") - -

 

-
-- 2.49.0