FIN 5.3.1 中文文档

外观

webmod ​

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793914828/FIN+5.3.1+webmod 中文整理基于 FIN 5.3.1

导读： WebMods 标准库

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读） ​

  • classes
  • docs
  • Overview
  • FileMod
  • RouteMod
  • PipelineMod
  • LogMod
  • Slot Details
    • file
    • make
    • onService
    • dir
    • fields
    • filename
    • onStop
    • after
    • before
    • onStart
    • steps
    • routes

API 正文（英文） ​

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"

FileMod ​

const class FileMod : WebMod

FileMod is a web module which publishes a file or directory.

See pod doc

Constructors

makeConstructor with it-block, must set file

Fields

fileFile or directory to publish.

Methods

onService

Slot Details ​

file ​

const File file

File or directory to publish. This field must be configured in the constructor's it-block.

make ​

new make(|This|? f)

Constructor with it-block, must set file

onService ​

virtual override Void onService()

LogMod ​

const class LogMod : WebMod

LogMod is used log requests according to the W3C extended log file format.

See pod doc

Constructors

makeConstructor with it-block.

Fields

dirDirectory used to store log file(s).
fieldsFormat of the log records as a string of #Fields names.
filenameLog filename pattern.

Methods

onService
onStop

Slot Details ​

dir ​

const File dir := noDir

Directory used to store log file(s).

fields ​

const Str fields := ...

Format of the log records as a string of #Fields names. See pod doc

filename ​

const Str filename := ""

Log filename pattern. The name may contain a pattern between {} using the pattern format of DateTime.toLocale. For example to maintain a log file per month, use a filename such as "web-{YYYY-MM}.log".

make ​

new make(|This|? f := null)

Constructor with it-block.

onService ​

virtual override Void onService()

onStop ​

virtual override Void onStop()

PipelineMod ​

const class PipelineMod : WebMod

PipelineMod routes seriallly through a list of sub-WebMods.

See pod doc

Constructors

makeConstructor with it-block.

Fields

afterSteps to run serially regardless of WebRes.isDone after every request.
beforeSteps to run serially regardless of WebRes.isDone before every request.
stepsSteps to run serially until WebRes.isDone returns true.

Methods

onServiceService the pipeline.
onStartCall onStart on sub-mods.
onStopCall onStop on sub-mods.

Slot Details ​

after ​

const WebMod[] after := WebMod[,]

Steps to run serially regardless of WebRes.isDone after every request.

before ​

const WebMod[] before := WebMod[,]

Steps to run serially regardless of WebRes.isDone before every request.

make ​

new make(|This|? f)

Constructor with it-block.

onService ​

virtual override Void onService()

Service the pipeline.

onStart ​

virtual override Void onStart()

Call onStart on sub-mods.

onStop ​

virtual override Void onStop()

Call onStop on sub-mods.

steps ​

const WebMod[] steps := WebMod[,]

Steps to run serially until WebRes.isDone returns true.

RouteMod ​

const class RouteMod : WebMod

RouteMod routes a level of the URI path to sub-WebMods.

See pod doc

Constructors

makeConstructor with it-block.

Fields

routesMap of URI path names to sub-WebMods.

Methods

onService
onStartCall onStart on sub-mods.
onStopCall onStop on sub-mods.

Slot Details ​

make ​

new make(|This|? f)

Constructor with it-block.

onService ​

virtual override Void onService()

onStart ​

virtual override Void onStart()

Call onStart on sub-mods.

onStop ​

virtual override Void onStop()

Call onStop on sub-mods.

routes ​

const Str:WebMod routes := [Str:WebMod][:]

Map of URI path names to sub-WebMods. The name "index" is used for requests to the RouteMod itself.