Instaweb: Instant Web Publishing Tool

Noel Welsh and Dave Gurnell

{noel, dave} at untyped

Instaweb is a simple tool that makes it easier to run servlets in the PLT web server by:

• configuring the web server to run a single servlet;

• running the web server in a handy interactive shell;

• making it easy to set up static content like HTML, CSS and Javascript files.

1 Usage

If you have a servlet in a module called "servlet.ss" in the current directory, you can run it in the web server simply by requiring Instaweb.plt and calling the instaweb function with no arguments:

#lang scheme/base

(require (planet schematics/instaweb/instaweb))

(instaweb)

This will start the web server on port 8765 and listening only to connections from localhost (127.0.0.1). You can view your servlet by visiting http://127.0.0.1:8765/ in your web browser.

You can override these defaults, and many others, by passing keyword arguments to the instaweb function. For example, you can choose a different port:

  (instaweb #:port 4567)

or use a different file name for your servlet:

  (instaweb #:servlet-path "my-servlet.ss")

If you give a relative path for the servlet, as above, it is resolved relative to the value of the current-directory parameter.

If you want to make your use of Instaweb unaffected by the value of current-directory, use the define-runtime-path form from the scheme/runtime-path package to define the path to the servlet:

#lang scheme/base

(require (for-syntax scheme/base)

scheme/runtime-path)

(define-runtime-path servlet-path "./servlet.ss")

(instaweb #:servlet-path servlet-path)

If you want to serve static files in addition to your servlet you can put them in a directory called htdocs (again, relative to the current-directory parameter) or specify a different path to instaweb:

  (instaweb #:htdocs-path '("public-html"))

Note that you give a list of paths, so you can specify multiple directories. Files matching the path portion of the request URL are searched for in these directories. If no matching file is found control is passed to your servlet. This means your servlet will receive all HTTP requests that do not match the path of an existing file.

If the instaweb procedure is not sufficient for your needs, you find other parts of the provided API useful instead.

2 API

(require (planet schematics/instaweb/instaweb))

The main API for Instaweb.

(instaweb  [ #:servlet-path servlet-path             #:servlet-lang servlet-lang             #: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-path   :   (U path? string?)       =   (build-path (current-directory) "servlet.ss")

servlet-lang   :   (U 'mzscheme 'scheme 'scheme/base 'web-server)       =   'scheme/base

port : integer? = 8765

listen-ip : (U string? #f) = "127.0.0.1"

htdocs-path   :   (listof (U path? string?))       =   (list (build-path (current-directory) "htdocs"))

mime-types-path   :   path?       =   (build-path (instaweb-directory) "mime.types")

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

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

Runs Instaweb on an application that is packaged as a single servlet:

• servlet-path is the path to the file containing the servlet code;

• servlet-lang specifies the module language in which the servlet is written. Possible values include 'scheme, 'scheme/base, 'mzscheme and 'web-server. 'scheme, 'scheme/base and 'mzscheme servlets are currently treated the same way; 'web-server servlets are written in the special web language and must be treated differently;

• port specifies the TCP port on which the web server should run;

• listen-ip specifies the client machine to respond to: string values restrict the web server to only listen for requests from the specified IP (useful for running the server behind another web server such as Apache); #f allows the server to respond to requests from any machine;

• htdocs-path is a list of paths to directories containing static content such as HTML, CSS and Javascript. Instaweb scans these paths for existing files, and passes requests to non-existant files on to the servlet;

• mime-types-path is the path to a file containing mappings form file extensions to MIME types. The argument defaults to an Instaweb supplied file;

• servlet-namespace is a list of require-forms of modules that should be shared between the servlet and the code calling Instaweb. For example:

    (instaweb #:servlet-namespace '((planet untyped/snooze/snooze)))

  This is useful for passing configuration information to the code in the servlet. The servlet loads separate copies of other modules, so information cannot be shared with the top level application.

• servlet-exn-handler is a function that creates a response if the servlet raises an exception.

All relative paths are resolved relative to the current-directory.

(instaweb/dispatcher   #:app-dispatcher dispatcher      [ #:servlet-lang servlet-lang       #:port port       #:listen-ip listen-ip       #:htdocs-path htdocs-path       #:mime-types-path mime-types-path       #:servlet-namespace servlet-namespace])

→ void?

dispatcher : dispatcher?

servlet-lang   :   (U 'mzscheme 'scheme 'scheme/base 'web-server)       =   'scheme/base

port : integer? = 8765

listen-ip : (U string? #f) = "127.0.0.1"

htdocs-path   :   (listof (U path? string?))       =   (list (build-path (current-directory) "htdocs"))

mime-types-path   :   path?       =   (build-path (instaweb-directory) "mime.types")

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

Like instaweb but accepts does not require the main web application to be a servlet. Arguments are the same as those for instaweb except for app-dispatcher, which must be a dispatcher function (from a connection and a request to a response).

(run-server   #:port port             #:listen-ip listen-ip             #:dispatcher dispatcher)   →   (-> void?)

port : integer?

listen-ip : (U string? #f)

dispatcher : dispatcher?

Runs the web server using the given parameters. Returns a thunk that, when called, shuts down the web server. The dispatcher must be a complete application dispatcher, that serves static as well as dynamic content.

(console-loop run-server) → void?

run-server : (-> (-> void?))

Given a thunk that runs the web server (and returns a thunk that shuts down said server), creates a console that allows you to stop or restart the web server.

3 Defaults

(require (planet schematics/instaweb/dispatcher))

Provides contructors for the various parts of the Instaweb dispatcher. This might be useful if you get into the plumbing of Instaweb.

(make-application-dispatcher       #:servlet-lang servlet-lang       #:servlet-path servlet-path       #:servlet-namespace servlet-namespace       #:servlet-exn-handler servlet-exn-handler)

→ dispatcher?

servlet-lang : (U 'mzscheme 'scheme 'scheme/base 'web-server)

servlet-path : path?

servlet-namespace : (listof require-spec)

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

Constructs a dispatcher that sends all URLs to the specified servlet. Parameters are as for instaweb.

(make-instaweb-dispatcher   #:app-dispatcher app-dispatcher       #:htdocs-path htdocs-path       #:mime-types-path mime-types-path)

→ dispatcher?

app-dispatcher : dispatcher?

htdocs-path : (listof (U path? string?))

mime-types-path : path?

Constructs a dispatcher you can pass to the web server. Parameters are as for instaweb/dispatcher.

4 Tips and caveats

Unlike the default web server configuration, your servlet is not required to reside under a URL beginning with "/servlets/<file-name>". If receives all requests that don’t match a file in the htdocs direcory.

Calling your servlet is the last step in the web-server dispatching process. Your servlet should return a 404 response if it receives a URL it cannot process.

If you want to run a Instaweb launched servlet on a server you probably don’t want an interactive terminal. This is fine: Instaweb will detect when it doesn’t have a terminal and so avoid filling your logs with rubbish. Simply spawn a new process to run MzScheme and prevent signals from interferring with it:

  nohup mzscheme run-servlet.ss &

5 Acknowledgements

Danny Yoo provided patches to install the servlet-exn-handler.

Matthew Flatt, Jens Axel Soegaard, and Dave Herman for suggestions for dealing with a missing terminal, and suspending the main thread.

Eric Hanchrow, for pointing out documentation typos.