Configuring ESP

Set of property keys that map server-side properties to client-side properties to send to the client. Mappings select a subset of properties so the entire JSON configuration is not sent to the client. For example:

This computes a JSON string with properties "auth" and "timeouts" to send to the client.

Ordered set of scripts to send to the client when parsing the ESP scripts() API. This may include the "*" wildcard to match any file or "**" to match any file in any directory. For example:

Define whether the directory contains an ESP application or stand-alone ESP pages. For example:app: true

An ESP application follows an MVC design pattern and provides controllers to respond to client requests and views to render responses. An ESP application differs from stand-alone ESP pages in that it pre-configures ESP for the MVC pattern. This includes defining the standard directories: cache, controllers, contents, db, layouts, migrations, paks and partials.

Define external ESP applications to load. ESP can host multiple applications by defining the URI prefix and ESP configuration file for each application. This directive takes three forms. The first is just a simple string with the path to the configuration file for a single application. The URI prefix is determined by the last path segment before the esp.json filename.

The second form takes an array of esp configuration file names. Both these forms may use wild-cards in the filename. The last form is an array of URI prefix and config file properties for each application.

Examples: apps: 'blog/esp.json', apps: [ 'apps/*/esp.json', 'test/*/esp.json' ], apps: [ { prefix: '/blog', config: 'apps/blog/esp.json' } ]

If there is no attach property, the virtual host will attach to all listening endpoints.

Enable serving of compressed content. ESP can serve files compressed with gzip and with an additional .gz extension. ESP adds the appropriate HTTP header so the browser can automatically decompress. Ideal for big files or slow networks.

If the Expansive exp-gzip extension is installed, suitable static content will be automatically gzipped.

A single server may support multiple virtual hosts on a shared IP address endpoint. The client HTTP request includes a Host header that specifies the desired hostname. The supported virtual hosts are configured via the hosts directive which specifies one more more virtual host configurations.

Each virtual host may include other directives to customize the configuration and routes for that specific host. Each host may nominate the specific listen endpoints for the host via the attach property. Without an attach property, the virtual host will attach to all listening endpoints.

Example:

hosts: [ {
    name: '*embedthis.com',
    attach: '*:80',
}, {
    name: '*appwebserver.org',
    attach: [
        '*:80',
        '*:4443'
    ],
}]

Matching URI regular expression for requests to be served by the current route. The route pattern is an enhanced JavaScript-compatibile regular expression. It is enhanced by optionally embedding braced tokens "{name}" in the pattern. During request URI matching, these tokens are extracted and defined in the request params and are available to the request and to route targets. To use the standard regular expression repeat syntax {}, quote the braces with back quote \.

Sub-expressions and token expressions are also available in route targets as numbered tokens $N. For example:

This will enable the target $1.${request.Language=fr}.$2.

Use ^ to anchor to the start of the URI and $ for the end of the URI. If the pattern does not start with ^, the route pattern will have its parent route prefix prepended to the pattern.

Collection of redirection rules. These include the failing URI, destination URI and redirection status.

Alternatively, a rule may be just the string "https://" in which case all HTTP content will be redirected over HTTPS.

Create routes sets for the requested resources. Route sets select pre-defined route sets. Some of the available sets are: 'esp-server' and 'esp-restful'. Resource groups create RESTful routes for a resource that has multiple instances. Singletons create RESTful routes for singleton resources.

timeouts: {
    exit: '5secs',
    parse: '5secs',
    inactivity: '30secs',
    request: 'unlimited',
    session: '30mins',
}

The trace properties are:

• location — Filename to trace to. May also be 'stdout', or 'stderr'.
• level — Trace level (0-5) with 5 being the most verbose.
• backup — Number of trace backups to keep.
• anew — Start trace log anew each time the application restarts.
• size — Maximum size of the trace log before it will be restarted.
• timestamp — Write a timestamp at this frequency.
• maxContent — Maximum size of request body content to trace. Defaults to 40K.

Note: restarting the server or creating a new ESP session will invalidate XSRF tokens. In this case, the form will need to be reloaded to generate a new token.

• location — Filename to log to. May also be 'stdout', or 'stderr'.
• level — Trace level (0-5) with 5 being the most verbose.
• backup — Number of log backups to keep.
• anew — Start log anew each time the application restarts.
• size — Maximum size of the log before it will be restarted.
• timestamp — Write a timestamp at this frequency.

Configure the user session details. The cookie property can define a unique prefix to use for the session cookie. The default session cookie prefix is: "-http-session-". If set to 'none', then no cookie is emitted. The visibleproperty specifies whether the cookie is readable by scripts in the browser. By default, the session cookie is not visible to Javascript. It is desirable to keep the session cookie invisible to minimize XSS security vulnerabilities.

ESP implements this by adding the httpOnly option on the Set-Cookie response header.

The persist property defines if the cookie is persisted to disk in the browser. If false, the browser discards the cookie when the browser exits. Otherwise the cookie is retained until the session timeout limit expires.