Overview
The webmod pod defines a library for web modules which may be composed together:
- FileMod: publish static files
- RouteMap: route to a sub-module based on a URI path name
- PipelineMod: run through a serial list of sub-modules
- LogMod: logs using W3C extended log format
FileMod
FileMod
is a simple way to publish static files under a base URI. FileMod may be used with a single file or with a directory. If using FileMod with a directory, then any request which maps to a directory which does not end in slash is redirected to include a trailing slash. Requests to directories are mapped to "index.html" in that directory.
Let's assume we have the following file structure:
pub/
index.html
alpha.html
icon.png
foo/
index.html
beta.html
Let's assume this top level route mapping:
RouteMod
{
routes =
[
"favicon.ico": FileMod { file=`pub/icon.png`.toFile },
"stuff": FileMod { file=`pub/`.toFile }
]
}
Single file modules map directly to the file:
/favicon.ico => pub/icon.png
/favicon.ico?q => pub/icon.png // queries ignored
/favicon.ico/foo => 404 // deeper paths return 404
Directories map files based on WebReq.modRel
:
/stuff => redirect /stuff/
/stuff/ => /stuff/index.html
/stuff/index.html => /stuff/index.html
/stuff/alpha.html => /stuff/alpha.html
/stuff/foo => redirect /stuff/foo/
/stuff/foo/ => /stuff/foo/index.html
/stuff/foo/beta.html => /stuff/foo/beta.html
RouteMod
RouteMod
is a composition module used to route path names in a URI to sub-modules. RouteMod maps the first path name in WebReq.modRel
to a sub module via the routes
map. If modRel
is the empty path, then RouteMod will route to the name "index".
Example configuration with nested routes:
root = RouteMod
{
routes =
[
"index": top,
"foo": foo,
"bar": RouteMod
{
routes =
[
"index": bar,
"alpha": alpha,
]
}
]
}
Request uri to module mappings:
/ => top
/index/ => top
/index/x => top
/foo => foo
/foo/index => foo
/foo/a/b => foo
/bar => bar
/bar/ => bar
/bar/alpha => alpha
/bar/alpha/x => alpha
PipelineMod
PipelineMod
is a composition module used to run a request through a series of sub-modules. The lifecycle of a PipelineMod request:
- Call each module in
before
- Call each module in
steps
as long as WebRes.isDone
returns false
- Call each module in
after
The before, steps, and after lists are processed in their declaration order. Every module declared in before and after is called for every request regardless of the WebRes.isDone
state. But the modules declared steps are only processed as long as WebRes.isDone
is false.
LogMod
LogMod
class is used to generate a server log file for all HTTP requests in the W3C Extended Log File Format. Logging is best done a step in the PipelineMod.after
. See FileLogger
to configure datetime patterns for your log files.
The fields
property configures the format of the log records. It is a string of field names separated by a space. The following field names are supported:
- date: UTC date as DD-MM-YYYY
- time: UTC time as hh:mm:ss
- c-ip: the numeric IP address of the remote client socket
- c-port: the IP port of the remote client socket
- cs-method: the request method such as GET
- cs-uri: the encoded request uri (path and query)
- cs-uri-stem: the encoded path of the request uri
- cs-uri-query: the encoded query of the request uri
- sc-status: the return status code
- time-taken: the time taken to process request in milliseconds
- cs(HeaderName): request header value such
User-Agent
If any unknown fields are specified or not available then "-" is logged. The default format is:
date time c-ip cs(X-Real-IP) cs-method cs-uri-stem cs-uri-query
sc-status time-taken cs(User-Agent) cs(Referer)
Example log record with this format:
2011-02-25 03:22:45 0:0:0:0:0:0:0:1 - GET /doc - 200 247
"Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US) AppleWebKit/534.10 (KHTML, like Gecko) Chrome/8.0.552.237 Safari/534.10"
"http://localhost/tag"