1 Deprecation notice
1.1 Migrating to serve/ servlet without using Dispatch
1.2 Migrating to serve/ servlet using Dispatch
2 Using Instaserlvet
3 Instaservlet API
go!
3.1 How The Servlet Is Run
Version: 4.1.3.3

Instaservlet

by Noel Welsh and Dave Gurnell

{noel, dave} at untyped

Instaservlet has been deprecated as of PLT 4.1.3. See the Deprecation notice for more information.

Instaservlet is an extremely fast way to run a web application in the PLT Web Server. You provide a function that accepts a request argument and returns a 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.

1 Deprecation notice

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

Instaservlet users are advised to rewrite Instaweb applications using serve/servlet. This is made considerably easier using the Dispatch package from Untyped.

The next section describes how to migrate from Instaweb to serve/servlet if you are not using Dispatch; the following section describes the transition if you are using Dispatch.

1.1 Migrating to serve/servlet without using Dispatch

Instaservlet and serve/servlet use filesystem and 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:

To recreate Instaservlet-style behaviour using serve/servlet, use code like the following:

  (require net/url
           web-server/http
           web-server/servlet-env
           web-server/dispatchers/dispatch)
  
  ; Helper procedures --------------------------------
  
  ; 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]
            ; and so on...
            [else #f])))
  
  ; request -> response
  (define (make-not-found-response request)
    ; create a pretty 404 response...)
  
  ; Servlet procedure --------------------------------
  
  ; request -> response
  (define (start request)
    (when (static-file-url? (request-uri request))
      (next-dispatcher))
    ; continue handling the request...)
  
  ; Main program body -------------------------------
  
  (serve/servlet
   start
   ; blank regexp passes all requests to the servlet:
   #:servlet-regexp #rx""
   ; initial URL to send to the browser:
   #:servlet-path "/"
   ; default port is different:
   #:port 8765
   ; prettify 404 messages (optional):
   #:file-not-found-responder make-not-found-response)

1.2 Migrating to serve/servlet using Dispatch

As of version 1.6, Dispatch interoperates with serve/servlet as you might expect. Rather than displaying a 404 page when none of the site URLs match, it calls next-dispatcher.

To recreate Instaservlet-style behaviour using serve/servlet and Dispatch, use code like the following:

  (require web-server/http
           web-server/servlet-env
           web-server/dispatchers/dispatch
           (planet untyped/dispatch)
           (planet untyped/dispatch/response))
  
  ; Site definition ----------------------------------
  
  ; The site is normally written in a different module...
  ; see the Dispatch documentation for more information.
  (define-site my-site
    ([(url "/") home]
     ; and so on...))
  
  ; Servlet procedure --------------------------------
  
  ; request -> response
  (define (start request)
    ; Dispatch will handle the static file case:
    (dispatch my-site request))
  
  ; Main program body -------------------------------
  
  (serve/servlet
   start
   ; blank regexp passes all requests to the servlet:
   #:servlet-regexp #rx""
   ; initial URL to send to the browser:
   #:servlet-path "/"
   ; default port is different:
   #:port 8765
   ; pretty 404 messages provided by Dispatch:
   #:file-not-found-responder make-not-found-response)

2 Using Instaserlvet

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

  (require (planet untyped/instaservlet/instaservlet))
  
  (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 "go!". See the Instaservlet API for details.

3 Instaservlet API

 (require (planet untyped/instaservlet/instaservlet))

The main function is go!:

(go! servlet    
  [#: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 : (-> request any)
  port : integer/c = 8765
  listen-ip : string? = "127.0.0.1"
  htdocs-path : (listof (or/c path? string?))
   = default-htdocs-path
  mime-types-path : path? = default-mime-types-path
  servlet-namespace : (listof require-spec)
   = default-servlet-namespace
  servlet-exn-handler : (-> url? exn? response)
   = default-servlet-exn-handler

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.

3.1 How The Servlet Is Run

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

These settings will be made customisable in future releases on Instaservlet.