#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}}}

@italic{Instaweb has been deprecated as of PLT 4.1.3. See the @secref{deprecation-notice} for more information.}

Instaweb makes running servlets in the PLT web server simple 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 "deprecation-notice"]{Deprecation notice}

As of version 4.1.3, the PLT Web Server contains a quick-start procedure called @scheme[serve/servlet]. This procedure makes Instaweb largely unnecessary: the package has consequently been deprecated and no future updates are planned.

Instaweb users are advised to rewrite their applications using @scheme[serve/servlet]. This is made considerably easier using the @link["http://planet.plt-scheme.org/display.ss?package=dispatch.plt&owner=untyped"]{Dispatch} package from Untyped.

The next section describes how to migrate from Instaweb to @scheme[serve/servlet] if you are @italic{not} using Dispatch; the following section describes the transition if you @italic{are} using Dispatch.

@subsection[#:tag "serve/servlet"]{Migrating to @scheme[serve/servlet] without using Dispatch}

Instaweb requires you to write your web application in a separate "servlet" module. @scheme[serve/servlet] removes this requirement by allowing you to pass a controller procedure directly as an argument. This is similar to the @scheme[go!] procedure in Instaservlet.

Instaweb and @scheme[serve/servlet] use @italic{filesystem} and @italic{servlet dispatcher} procedures to handle requests. The dispatchers are chained together such that if one cannot handle a request the other is invoked. However, the order of dispatch is different:

@itemize{
  @item{
    Instaweb calls filesystem dispatcher first. If no matching file is found, it calls the servlet dispatcher instead.}
  @item{
    @scheme[serve/servlet] checks to see if the URL matches a user-specified @scheme[#:servlet-regexp]: if it does, the procedure calls the servlet dispatcher. If the URL doesn't match, or if the servlet can't handle the request, the procedure calls the filesystem dispatcher instead.
    
    As of PLT 4.1.3, a servlet can signal that it cannot handle a request by calling the @scheme[next-dispatcher] procedure from the @scheme[web-server/dispatchers/dispatch] module.}}

To recreate Instaweb-style behaviour using @scheme[serve/servlet], use code like the following:

@schemeblock[
  (require net/url
           web-server/http
           web-server/servlet-env
           web-server/dispatchers/dispatch
           (code:comment "Servlet module:")
           (code:comment "- provides a 'start' procedure")
           (code:comment "- optionally provides a continuation 'manager'")
           "servlet.ss")
  
  (code:comment "Helper procedures --------------------------------")

  (code:comment "url -> boolean")  
  (define (static-file-url? url)
    (let ([str (url->string url)])
      (cond [(regexp-match #rx"^/stylesheets/" str) #t]
            [(regexp-match #rx"^/javascript/"  str) #t]
            (code:comment "and so on...")        
            [else #f])))
  
  (code:comment "request -> response")
  (define (make-not-found-response request)
    (code:comment "create a pretty 404 response..."))
  
  (code:comment "Servlet procedure --------------------------------")

  (code:comment "request -> response")  
  (define (start-wrapper request)
    (when (static-file-url? (request-uri request))
      (next-dispatcher))
    (start request))

  (code:comment "Main program body -------------------------------")

  (serve/servlet
   start-wrapper
   (code:comment "blank regexp passes all requests to the servlet:")
   #:servlet-regexp #rx""
   (code:comment "initial URL to send to the browser:")
   #:servlet-path "/"
   (code:comment "default port is different:")
   #:port 8765
   (code:comment "customise the continuation manager: ")
   (code:comment "omit this argument if your servlet module does not ")
   (code:comment "provide a 'manager' identifier")
   #:manager manager
   (code:comment "prettify 404 messages (optional):")
   #:file-not-found-responder make-not-found-response)]

@subsection[#:tag "dispatch"]{Migrating to @scheme[serve/servlet] using Dispatch}

As of version 1.6, Dispatch interoperates with @scheme[serve/servlet] in an intuitive manner: it calls @scheme[next-dispatcher] when none of the site's URL patterns rather than displaying a 404 page.

To recreate Instaweb-style behaviour using @scheme[serve/servlet] and Dispatch, use code like the following:

@schemeblock[
  (require web-server/http
           web-server/servlet-env
           web-server/dispatchers/dispatch
           (planet untyped/dispatch)
           (planet untyped/dispatch/response)
           (code:comment "Servlet module:")
           (code:comment "- provides a 'start' procedure that uses Dispatch")
           (code:comment "- optionally provides a continuation 'manager'")
           "servlet.ss")
  
  (code:comment "Main program body -------------------------------")

  (serve/servlet
   (code:comment "provided by servlet.ss:")
   start
   (code:comment "blank regexp passes all requests to the servlet:")
   #:servlet-regexp #rx""
   (code:comment "initial URL to send to the browser:")
   #:servlet-path "/"
   (code:comment "default port is different:")
   #:port 8765
   (code:comment "customise the continuation manager: ")
   (code:comment "omit this argument if your servlet module does not ")
   (code:comment "provide a 'manager' identifier")
   #:manager manager
   (code:comment "pretty 404 messages provided by Dispatch:")
   #:file-not-found-responder make-not-found-response)]

@section[#:tag "usage"]{Using Instaweb}

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 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, try the @scheme[serve/servlet] procedure in the PLT web server.

@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")]
	                  [#: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?]{
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[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.}}

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

} @;{end defmodule}

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

Your servlet is not required to reside under a URL beginning with @filepath{/servlets/<file-name>}. It 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}

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.