Instaservlet

by Noel Welsh

noel at untyped

Instaservlet is the fastest way to get a servlet running in the web server. You provide a function that takes a request and returns a response. Instaservlet sets up the web server with sensible defaults, and runs your servlet in a wrapper that handles the details of instance and continuation expiry for you.

1 Using Instaserlvet

Using Instaservlet is as simple as requiring the Instaservlet module and calling go! with your servlet function. For example, the following is a complete servlet that uses Instaservlet to handle all web-server configuration:

(require (planet untyped/instaservlet/instaservlet))

(define (servlet request)

'(html (head (title "It's working!"))

(body (h1 "Instaservlet is in the house!"))))

(go! servlet)

That is basically all there is to Instaservlet. By default the web-server listens on port 8765 to connections from the localhost only. You can change this by passing optional arguments to "go!". See the Instaservlet API for details.

2 Instaservlet API

(require (planet untyped/instaservlet/instaservlet))

The main function is go!:

(go!   servlet            [ #:port port             #:listen-ip listen-ip             #:htdocs-path htdocs-path             #:mime-types-path mime-types-path             #:servlet-namespace servlet-namespace             #:servlet-exn-handler servlet-exn-handler])   →   void?

servlet : (-> request any)

port : integer/c = 8765

listen-ip : string? = "127.0.0.1"

htdocs-path   :   (listof (or/c path? string?))       =   default-htdocs-path

mime-types-path : path? = default-mime-types-path

servlet-namespace   :   (listof require-spec)       =   default-servlet-namespace

servlet-exn-handler   :   (-> url? exn? response)       =   default-servlet-exn-handler

Runs the given servlet in a web-server that has been setup (using Instaweb) with the given parameters (all of which are optional). By default the web server runs on port 8765 and listens only to connections from the localhost. Refer to the Instaweb documentation for more details.

2.1 How The Servlet Is Run

Instaweb takes care of some important servlet configuration details for you:

• The servlet uses the web-server’s version 2 API

• Memory is managed with the LRU manager, which is much more robust than the timeout manager. The memory limit is set to 64MB. Continuations start with 24 life points. Life points are deducted at the rate of one every 10 minutes, or one every 5 seconds when the memory limit is exceeded. Hence the maximum life time for a continuation is 4 hours, and the minimum is 2 minutes.

• A default instance-expiration-handler is installed, so users see a sensible error message on continuation expiry.

These settings will be made customisable in future releases on Instaservlet.