
Instead of serving files from a special directory verbatim, the Web server executes the contained Scheme code and serves the output. By default, the special directory is named "servlets" within the "default-web-root" of the "web-server" collection directory. Each file in that directory must evaluate to a servlet.
A servlet is a unit/sig that imports the servlet^
signature and exports nothing. (Search in help-desk for more information on unit/sig and on signatures.) To construct a unit/sig with the appropriate imports, the servlet must require the two modules providingunit/sigs and the servlet^ signature:
(require (lib "unitsig.ss")
(lib "servlet-sig.ss" "web-server"))
(unit/sig ()
(import servlet^)
...insert servlet code here...)The last value in the unit/sig must be a response to an HTTP request.
A Response is one of the following:
X-expression representing HTML help-desk.)(listof string) where
(make-response/full code message seconds mime extras body) where
(listof (cons symbol string)) containing extra headers for redirects, authentication, or cookies.(listof string)Evaluating (require (lib "servlet-sig.ss" "web-server")) loads
the servlet^ signature consisting of the following imports:
request, where a request is (make-request method uri headers bindings host-ip client-ip), where
(Union 'get 'post)URL net collection in help-desk for details(listof (cons symbol string)) (listof (cons symbol string)) The path part of the URL suplies the file path to the servlet relative to the "servlets" directory. However, paths may also contain extra path components that servlets may use as additional input. For example all of the following URLs refer to the same servlet:
http://www.plt-scheme.org/servlets/my-servlethttp://www.plt-scheme.org/servlets/my-servlet/extrahttp://www.plt-scheme.org/servlets/my-servlet/extra/directoriesThe above imports support handling a single input from a Web form. To ease the development of more interactive servlets, the servlet^ signature also provides the following functions:
send/suspend : (str -> Response) -> requestURL that can be used in the document. The argument function must produce a
response corresponding to the document's body. Requests to the
given URL resume the computation at the point
send/suspend was invoked. Thus, the argument function normally
produces an HTML form with the "action" attribute set to the provided
URL. The result of send/suspend represents the
next request.
send/finish : Response -> doesn't return adjust-timeout! : Nat -> VoidThe servlet-helpers module, required with
(require (lib "servlet-helpers.ss" "web-server")) provides a few additional functions helpful for constructing servlets: extract-binding/single : sym (listof (cons sym str)) -> strThis extracts a single value associated with sym in the form bindings. If multiple or zero values are associated with the name, it raises an exception.extract-user-pass : (listof (cons sym str)) -> (U #f (cons str str))(define (extract-user-pass headers) ...)Servlets may easily implement password based authentication by extracting password information from the HTTP headers. The return value is either a pair consisting of the username and password from the headers or #f if no password was provided.The Web server caches passwords and servlets for performance reasons. Requesting the URL
http://my-host/conf/refresh-passwordsreloads the password file. After updating a servlet, loading the URL http://my-host/conf/refresh-servletscauses the server to reload each servlet on the next invocation. This loses any per-servlet state (not per servlet instance state) computed before the unit invocation.