FIN 5.3.1 中文文档

外观

wisp ​

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

导读： Fantom 捆绑了 WispService，它完全用 Fantom 代码实现了一个网络服务器——所以你可以在不必麻烦安装额外软件的情况下使用它。

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

目录（导读） ​

  • mixins
  • classes
  • docs
  • Overview
  • Test Setup
  • Configuration
  • HTTPS Configuration
  • wisp::Main
  • Slot Details
    • onService
    • addr
    • errMod
    • extraResHeaders
    • httpPort
    • httpsPort
    • make
    • maxThreads
    • onStart
    • onStop
    • root
    • sessionCookieName
    • sessionStore
    • socketConfig
    • delete
    • load
    • save
    • service

概述（中译） ​

Fantom 附带了 WispService，它完全用 Fantom 代码实现了一个网络服务器——所以你可以在不必麻烦安装额外软件的情况下使用它。

测试设置

你可以直接从 fansh 使用可配置端口运行测试 wisp 服务器：

fansh wisp::WispService { httpPort = 8080 }.start fan.wisp.WispService@5a9de6 [16:22:49 30-11-09] [信息] [网络] http 已在端口 8080 启动

如果它运行正常，你应该能够访问 http://localhost:8080/ 并看到测试页面。

API 正文（英文） ​

Configuration ​

Wisp is easily configured by installing a root WebMod which is responsible for serving all requests to the server. Typically you will install a composition WebMod to setup your pipeline and routing configuration.

See the following examples for how to setup a daemon script with various WebMod configurations:

  • web-hello: single, simple custom root webmod
  • web-demo: illustrates use of many different webmods
  • js-demo: configuration used to serve up FWT in browser examples

HTTPS Configuration ​

Wisp can be configured to serve HTTPS connection by setting the https port with the -httpsPort option. Wisp requires a keystore to serve https connections. A keystore is a repository of security certificates (either authorization or public key certificates) that can be used for TLS encryption. The keystore should contain the public and private key for your web server.

Wisp uses the following conventions for loading the keystore:

  1. The keystore must be PKCS12 formatted
  2. The keystore must have password "changeit"
  3. The keystore must have name keystore.p12
  4. The keystore must reside in etc/inet/keystore.p12 of your Fantom installation

Java provides a utility called keytool that can be used for generating and managing keystore files. For testing purposes, you can create a self-signed certificate and add it to a new pkcs12 keystore using the following command (make sure to use "changeit" as the password when prompted):

$ keytool -genkey \
          -alias my.domain.com \
          -keyalg RSA \
          -storetype pkcs12 \
          -keystore /path/to/etc/inet/keystore.p12

The following article contains many useful examples of working with keystores. The examples all use the JKS keystore format, so make sure to add the -storetype pkcs12 option if you attempt to duplicate any of the commands.

If you have a JKS formatted keystore, you can convert it to PKCS12 using the following command:

$ keytool -importkeystore \
          -srckeystore keystore.jks \
          -srcalias my.domain.com \
          -destkeystore keystore.p12 \
          -deststoretype PKCS12

wisp::Main ​

For the common case where a single WebMod is used, wisp can be run directly from the command line:

$ fan wisp
Usage:
  wisp [options] <mod>
Arguments:
  mod    qualified type name for WebMod to run
Options:
  -help, -?           Print usage help
  -addr <Str>         IP address to bind to
  -httpPort <Int>     IP port to bind for HTTP (default 8080)
  -httpsPort <Int>    IP port to bind for HTTPS (disabled unless set)

For example:

$ fan wisp myPod::MyWebMod
[16:43:16 17-Jul-15] [info] [web] http started on port 8080

WispDefaultErrMod ​

const class WispDefaultErrMod : WebMod

WispDefaultErrMod

Methods

onService

Slot Details ​

onService ​

virtual override Void onService()

WispService ​

const class WispService : Obj, Service

Simple web server services HTTP/HTTPS requests to a top-level root WebMod. A given instance of WispService can be only be used through one start/stop lifecycle.

Example:

WispService { httpPort = 8080; root = MyWebMod() }.start

Constructors

makeConstructor with it-block

Fields

addrWhich IpAddr to bind to or null for the default.
errModWebMod which is called on internal server error to return an 500 error response.
extraResHeadersMap of HTTP headers to include in every response.
httpPortWell known TCP port for HTTP traffic.
httpsPortWell known TCP port for HTTPS traffic.
maxThreadsMax number of threads which are used for concurrent web request processing.
rootRoot WebMod used to service requests.
sessionCookieNameCookie name to use for built-in session management.
sessionStorePluggable interface for managing web session state.
socketConfigThe SocketConfig to use for creating sockets

Methods

onStart
onStop

Slot Details ​

addr ​

const IpAddr? addr := null

Which IpAddr to bind to or null for the default.

errMod ​

const WebMod errMod := initErrMod

WebMod which is called on internal server error to return an 500 error response. The exception raised is available in req.stash["err"]. The onService method is called after clearing all headers and setting the response code to 500. The default error mod may be configured via errMod property in etc/web/config.props.

extraResHeaders ​

const Str:Str extraResHeaders := initExtraResHeaders

Map of HTTP headers to include in every response. These are initialized from etc/web/config.props with the key "extraResHeaders" as a set of "key:value" pairs separated by semicolons.

httpPort ​

const Int? httpPort := null

Well known TCP port for HTTP traffic. The port is enabled if non-null and disabled if null.

httpsPort ​

const Int? httpsPort := null

Well known TCP port for HTTPS traffic. The port is enabled if non-null and disabled if null. If the http and https ports are both non-null then all http traffic will be redirected to the https port.

make ​

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

Constructor with it-block

maxThreads ​

const Int maxThreads := 500

Max number of threads which are used for concurrent web request processing.

onStart ​

virtual override Void onStart()

onStop ​

virtual override Void onStop()

root ​

const WebMod root := WispDefaultRootMod.<ctor>()

Root WebMod used to service requests.

sessionCookieName ​

const Str sessionCookieName := ...

Cookie name to use for built-in session management. Initialized from etc/web/config.props with the key "sessionCookieName" otherwise defaults to "fanws"

sessionStore ​

const WispSessionStore sessionStore := MemWispSessionStore.<ctor>(this)

Pluggable interface for managing web session state. Default implementation stores sessions in main memory.

socketConfig ​

const SocketConfig socketConfig := SocketConfig.cur

The SocketConfig to use for creating sockets

WispSessionStore ​

const mixin WispSessionStore

Pluggable hooks for Wisp session storage.

Methods

deleteDelete any resources used by the given session id
loadLoad the session map for the given id, or if it doesn't exist then create a new one.
onStartCallback when WispService is started
onStopCallback when WispService is stopped
saveSave the given session map by session id.
serviceParent web service

Slot Details ​

delete ​

abstract Void delete(Str id)

Delete any resources used by the given session id

load ​

abstract Str:Obj? load(Str id)

Load the session map for the given id, or if it doesn't exist then create a new one.

onStart ​

virtual Void onStart()

Callback when WispService is started

onStop ​

virtual Void onStop()

Callback when WispService is stopped

save ​

abstract Void save(Str id, Str:Obj? map)

Save the given session map by session id.

service ​

abstract WispService service()

Parent web service