1 Usage
2 API
instaweb
instaweb/ dispatcher
run-server
console-loop
3 Defaults
make-application-dispatcher
make-instaweb-dispatcher
4 Tips and caveats
5 Acknowledgements
Version: 4.0.2.6

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:

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:

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.