#lang scribble/doc

@(require scribble/eval
          scribble/manual
          (for-label scheme/base
          web-server/servlet
          web-server/dispatchers/dispatch))

@title{@bold{Instaweb}: Instant Web Publishing Tool}

Noel Welsh and Dave Gurnell

@tt{{noel, dave} at @link["http://www.untyped.com"]{@tt{untyped}}}

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

@itemize{
  @item{configuring the web server to run a single servlet;}
  @item{running the web server in a handy interactive shell;}
  @item{making it easy to set up static content like HTML, CSS and Javascript files.}}

@section[#:tag "usage"]{Usage}

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

@schememod[scheme/base
  (require (planet schematics/instaweb/instaweb))
  (instaweb)]

This will start the web server on port 8765 and listening only to connections from @tt{localhost} (@tt{127.0.0.1}). You can view your servlet by visiting @link["http://127.0.0.1:8765/"]{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:

@schemeblock[
  (instaweb #:port 4567)]

or use a different file name for your servlet:

@schemeblock[
  (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 @scheme[current-directory] parameter.

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

@schememod[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:

@schemeblock[
  (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 @scheme[instaweb] procedure is not sufficient for your needs, you find other parts of the provided API useful instead.

@section[#:tag "api"]{API}

@defmodule[(planet schematics/instaweb/instaweb)]{

The main API for Instaweb.

@defproc[(instaweb [#:servlet-path        servlet-path
                                          (U path? string?)
                                          (build-path (current-directory) "servlet.ss")]
                   [#:servlet-lang        servlet-lang
                                          (U 'mzscheme 'scheme 'scheme/base 'web-server)
                                          'scheme/base]
                   [#:port                port
                                          integer?
                                          8765]
                   [#:listen-ip           listen-ip
                                          (U string? #f)
                                          "127.0.0.1"]
                   [#:htdocs-path         htdocs-path
                                          (listof (U path? string?))
                                          (list (build-path (current-directory) "htdocs"))]
                   [#:mime-types-path     mime-types-path
                                          path?
                                          (build-path (instaweb-directory) "mime.types")]
                   [#:servlet-namespace   servlet-namespace
                                          (listof require-spec)
                                          null]
                   [#:servlet-exn-handler servlet-exn-handler 
                                          (-> url? exn? response)
                                          default-servlet-exn-handler])
                 void?]{
Runs Instaweb on an application that is packaged as a single servlet:

@itemize{
  @item{@scheme[servlet-path] is the path to the file containing the servlet code;}

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

  @item{@scheme[port] specifies the TCP port on which the web server should run;}

  @item{@scheme[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); @scheme[#f] allows the server to respond
    to requests from any machine;}

  @item{@scheme[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;}

  @item{@scheme[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;}

  @item{@scheme[servlet-namespace] is a list of require-forms of modules that should be shared
    between the servlet and the code calling Instaweb. For example:

    @schemeblock[
      (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.}
  @item{@scheme[servlet-exn-handler] is a function that creates a response if the servlet raises 
    an exception.}}

All relative paths are resolved relative to the @scheme[current-directory].}

@defproc[(instaweb/dispatcher
          [#:app-dispatcher      dispatcher
                                 dispatcher?]
          [#:servlet-lang        servlet-lang
                                 (U 'mzscheme 'scheme 'scheme/base 'web-server)
                                 'scheme/base]
          [#:port                port
                                 integer?
                                 8765]
          [#:listen-ip           listen-ip
                                 (U string? #f)
                                 "127.0.0.1"]
          [#:htdocs-path         htdocs-path
                                 (listof (U path? string?))
                                 (list (build-path (current-directory) "htdocs"))]
          [#:mime-types-path     mime-types-path
                                 path?
                                 (build-path (instaweb-directory) "mime.types")]
          [#:servlet-namespace   servlet-namespace
                                 (listof require-spec)
                                 null])
                void?]{
Like @scheme[instaweb] but accepts does not require the main web application to be a servlet. Arguments are the same as those for @scheme[instaweb] except for @scheme[app-dispatcher], which must be a dispatcher function (from a connection and a request to a response).}

@defproc[(run-server [#:port port integer?]
                     [#:listen-ip listen-ip (U string? #f)]
                     [#:dispatcher dispatcher dispatcher?])
         (-> void?)]{
Runs the web server using the given parameters. Returns a thunk that, when called, shuts down the web server. The @scheme[dispatcher] must be a complete application dispatcher, that serves static as well as dynamic content.}

@defproc[(console-loop [run-server (-> (-> void?))]) 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.}

} @;{end defmodule}

@section[#:tag "defaults"]{Defaults}

@defmodule[(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.

@defproc[(make-application-dispatcher 
          [#:servlet-lang        servlet-lang        (U 'mzscheme 'scheme 'scheme/base 'web-server)]
          [#:servlet-path        servlet-path        path?]
          [#:servlet-namespace   servlet-namespace   (listof require-spec)]
          [#:servlet-exn-handler servlet-exn-handler (-> url? exn? response)])
         dispatcher?]{
Constructs a dispatcher that sends all URLs to the specified servlet. Parameters are as for @scheme[instaweb].}

@defproc[(make-instaweb-dispatcher
          [#:app-dispatcher  app-dispatcher  dispatcher?]
          [#:htdocs-path     htdocs-path     (listof (U path? string?))]
          [#:mime-types-path mime-types-path path?])
         dispatcher?]{
Constructs a dispatcher you can pass to the web server. Parameters are as for @scheme[instaweb/dispatcher].}

} @;{end defmodule}

@section[#:tag "tips"]{Tips and caveats}

Unlike the default web server configuration, your servlet is not required to reside under a URL beginning with @filepath{/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:

@commandline{
  nohup mzscheme run-servlet.ss &}

@section{Acknowledgements}

Danny Yoo provided patches to install the @scheme[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.