#lang scribble/doc

@(require scribble/manual)

@(require (for-label web-server/private/request-structs
	  	     web-server/private/response-structs
		     
		     "../instaservlet.ss"))

@title{Instaservlet}

by Noel Welsh

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

Instaservlet is the fastest way to get a servlet running in
the web server.  You provide a function that takes a
@scheme[request] and returns a @scheme[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.

@section{Using Instaserlvet}

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

@schemeblock[
(require
 (planet "instaservlet.ss" ("untyped" "instaservlet.plt" 1)))

(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 @scheme{go!}.  See the @secref{api} for
details.

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

To start you will want to require the Instaservlet module,
which has the PLaneT form:

@scheme[(planet "instaservlet.ss" ("untyped" "instaservlet.plt" 1))]

The main function is @scheme[go!]

@defproc[(go! (servlet             (-> request any))
              (#:port              port              integer/c                     8765)
              (#:listen-ip         listen-ip         string?                       "127.0.0.1")
              (#:htdocs-path       htdocs-path       (listof (or/c path? string?)) default-htdocs-path)
              (#:mime-types-path   mime-types-path   path?                         default-mime-types-path)
              (#:servlet-namespace servlet-namespace (listof require-spec)         default-servlet-namespace))
           void?]{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.}


@subsection{How The Servlet Is Run}

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

@itemize[
	@item{The servlet uses the web-server's version 2 API}
	@item{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.}
	@item{A default @tt{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.