pod webmod

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:

1. Call each module in before
2. Call each module in steps as long as WebRes.isDone returns false
3. 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"