Skip to content

AppServer

Jump to bottom
James Cheney edited this page Jun 13, 2017 · 4 revisions

In-process Web Server

This page describes Links's current in-process web server model. It is intended to simplify initial setup requirements, and to provide more options for persistent server-side behavior.

Basics

The Links web server is a wrapper of Cohttp, a light-weight Ocaml web server, adapted to the needs of Links web apps. It maintains a mapping of URLs to Links functions, called the routing table, and executes those functions upon receiving web requests.

It adds two new primitive server-side functions:

  • addRoute(uri, fun) adds a new entry to the routing table. If uri ends in a forward slash character, it is interpreted as a directory entry, and handles all URIs beginning with that directory. Otherwise, it must be matched exactly.  All URIs are treated as absolute, regardless of whether there is an initial slash.  The function fun should be of type String -> Page, where the argument provides the actual URI. Other details of the web request (query parameters, cookies, &c.) are accessed via global variables, as in other Links web apps. Note that the routing table is dynamic, and that requests will be handled by the most specific installed handler.
  • servePages() begins accepting web requests and routing them according to the routing table; it does not return.  As the routing table is dynamic, calling addRoute(uri, fun) after calling servePages() will add routes to the web server. Calling servePages() after servePages() has already been called in unsupported.

Otherwise, the web server makes no changes to Links execution model; programs using the web server APIs can be executed like any other server-side Links programs.

Shortcuts (as of Links v0.7)

The prelude contains two functions that wrap common case uses of the addRoute and servePages functions:

sig serveThis : (() ~> Page) ~> ()

sig serveThese : ([(String,() ~> Page)]) ~> ()

The first takes a function from unit to page, adds it as the default route handler, and starts the server. The second takes a list of pairs of strings (prefixes) and page handlers, installs all of them, and starts the server. In both cases, the page handlers ignore the inputs.

Configuration Settings

The in-process app server adds two new configuration settings, exposing Cohttp options.

  • host is a string giving the host's IP address
  • port is an integer giving the host port number

By default, these are localhost and 8080, respectively.

Serving static content

The web server also contains several workarounds to address the inability to serve static content using Links functions. 

  • The first is that URIs beginning with the value of the jsliburl setting are interpreted as JavaScript library requests, and so these requests are intercepted before checking the routing table.  They are mapped into the file system, starting at the new jslibdir setting. Note that for this to work properly, jsliburl should be an absolute URL.
  • Additional static routes can be added using the addStaticRoute(uri, path, mimeTypes) function, which maps URIs beginning with uri to paths beginning with path. Default MIME types can be overridden using the mimeTypes argument, which pairs extensions with their new MIME types.
Clone this wiki locally