On this page:
serve/ servlet
dispatch/ servlet
serve/ launch/ wait
Version: 4.1.5.3

1.2 Simple Single Servlet Servers

 (require web-server/servlet-env)

The Web Server provides a way to quickly configure and start a server instance.

Here’s a simple example:

  #lang scheme
  (require web-server/servlet
           web-server/servlet-env)
  
  (define (my-app request)
    `(html (head (title "Hello world!"))
           (body (p "Hey out there!"))))
  
  (serve/servlet my-app)

Suppose you’d like to change the port to something else, change the last line to:

  (serve/servlet my-app
                 #:port 8080)

By default the URL for your servlet is "http://localhost:8000/servlets/standalone.ss", suppose you wanted it to be "http://localhost:8000/hello.ss":

  (serve/servlet my-app
                 #:servlet-path "/hello.ss")

Suppose you wanted it to capture top-level requests:

  (serve/servlet my-app
                 #:servlet-path "/")

Or, perhaps just some nice top-level name:

  (serve/servlet my-app
                 #:servlet-path "/main")

Suppose you wanted to use a style-sheet ("style.css") found on your Desktop ("/Users/jay/Desktop/"):

  (serve/servlet my-app
                 #:extra-files-paths
                 (list
                  (build-path "/Users/jay/Desktop")))

These files are served in addition to those from the #:server-root-path "htdocs" directory. Notice that you may pass any number of extra paths.

Suppose you would like to start a server for a stateless Web servlet "servlet.ss" that provides start:

  #lang scheme
  (require "servlet.ss"
           web-server/servlet-env)
  
  (serve/servlet start #:stateless? #t)

Note: If you put the call to serve/servlet in the module like normal, strange things will happen because of the way the top-level interacts with continuations. (Read: Don’t do it.)

If you want to use serve/servlet in a start up script for a Web server, and don’t want a browser opened or the DrScheme banner printed, then you can write:

  (serve/servlet my-app
                 #:command-line? #t)

(serve/servlet 
  start 
  [#:command-line? command-line? 
  #:launch-browser? launch-browser? 
  #:quit? quit? 
  #:banner? banner? 
  #:listen-ip listen-ip 
  #:port port 
  #:ssl? ssl? 
  #:servlet-path servlet-path 
  #:servlet-regexp servlet-regexp 
  #:stateless? stateless? 
  #:stuffer stuffer 
  #:manager manager 
  #:servlet-namespace servlet-namespace 
  #:server-root-path server-root-path 
  #:extra-files-paths extra-files-paths 
  #:servlets-root servlets-root 
  #:servlet-current-directory servlet-current-directory 
  #:file-not-found-responder file-not-found-responder 
  #:mime-types-path mime-types-path 
  #:log-file log-file 
  #:log-format log-format]) 
  void
  start : (request? . -> . response/c)
  command-line? : boolean? = #f
  launch-browser? : boolean? = (not command-line?)
  quit? : boolean? = (not command-line?)
  banner? : boolean? = (not command-line?)
  listen-ip : (or/c false/c string?) = "127.0.0.1"
  port : number? = 8000
  ssl? : boolean? = #f
  servlet-path : string? = "/servlets/standalone.ss"
  servlet-regexp : regexp? = 
(regexp
 (format
  "^~a$"
  (regexp-quote servlet-path)))
  stateless? : boolean? = #f
  stuffer : (stuffer/c serializable? bytes?) = default-stuffer
  manager : manager?
   = (make-threshold-LRU-manager #f (* 1024 1024 64))
  servlet-namespace : (listof module-path?) = empty
  server-root-path : path-string? = default-server-root-path
  extra-files-paths : (listof path-string?)
   = (list (build-path server-root-path "htdocs"))
  servlets-root : path-string?
   = (build-path server-root-path "htdocs")
  servlet-current-directory : path-string? = servlets-root
  file-not-found-responder : (request? . -> . response/c)
   = 
(gen-file-not-found-responder
 (build-path
  server-root-path
  "conf"
  "not-found.html"))
  mime-types-path : path-string? = ....
  log-file : (or/c false/c path-string?) = #f
  log-format : log-format/c = 'apache-default

This sets up and starts a fairly default server instance.

start is loaded as a servlet and responds to requests that match servlet-regexp. The current directory of servlet execution is servlet-current-directory.

If launch-browser? is true, then a web browser is opened to "http://localhost:<port><servlet-path>".

If quit? is true, then the URL "/quit" ends the server.

If stateless? is true, then the servlet is run as a stateless

  #lang web-server

module and stuffer is used as the stuffer.

Advanced users may need the following options:

The server listens on listen-ip and port port.

If ssl? is true, then the server runs in HTTPS mode with "<server-root-path>/server-cert.pem" and "<server-root-path>/private-key.pem" as the certificates and private keys.

The servlet is loaded with manager as its continuation manager. (The default manager limits the amount of memory to 64 MB and deals with memory pressure as discussed in the make-threshold-LRU-manager documentation.)

The modules specified by servlet-namespace are shared with other servlets.

The server files are rooted at server-root-path (which is defaultly the distribution root.) File paths, in addition to the "htdocs" directory under server-root-path may be provided with extra-files-paths. These paths are checked first, in the order they appear in the list.

Other servlets are served from servlets-root.

If a file cannot be found, file-not-found-responder is used to generate an error response.

If banner? is true, then an informative banner is printed. You may want to use this when running from the command line, in which case the command-line? option controls similar options.

MIME types are looked up at mime-types-path. By default the "mime.types" file in the server-root-path is used, but if that file does not exist, then the file that ships with the Web Server is used instead. Of course, if a path is given, then it overrides this behavior.

If log-file is given, then it used to log requests using log-format as the format. Allowable formats are those allowed by log-format->format.

(dispatch/servlet 
  start 
  [#:regexp regexp 
  #:stateless? stateless? 
  #:stuffer stuffer 
  #:manager manager 
  #:namespace namespace 
  #:current-directory servlet-current-directory]) 
  dispatcher/c
  start : (request? . -> . response/c)
  regexp : regexp? = #rx""
  stateless? : boolean? = #f
  stuffer : (stuffer/c serializable? bytes?) = default-stuffer
  manager : manager?
   = (make-threshold-LRU-manager #f (* 1024 1024 64))
  namespace : (listof module-path?) = empty
  servlet-current-directory : path-string? = (current-directory)

serve/servlet starts a server and uses a particular dispatching sequence. For some applications, this nails down too much, but users are conflicted, because the interface is so convenient. For those users, dispatch/servlet does the hardest part of serve/servlet and constructs a dispatcher just for the start servlet.

The dispatcher responds to requests that match regexp. The current directory of servlet execution is servlet-current-directory.

If stateless? is true, then the servlet is run as a stateless

  #lang web-server

module and stuffer is used as the stuffer.

The servlet is loaded with manager as its continuation manager. (The default manager limits the amount of memory to 64 MB and deals with memory pressure as discussed in the make-threshold-LRU-manager documentation.)

The modules specified by servlet-namespace are shared with other servlets.

(serve/launch/wait make-dispatcher    
  [#:launch-path launch-path    
  #:banner? banner?    
  #:listen-ip listen-ip    
  #:port port    
  #:ssl-keys ssl-keys])  void
  make-dispatcher : (semaphore? . -> . dispatcher/c)
  launch-path : (or/c false/c string?) = #f
  banner? : boolean? = #f
  listen-ip : (or/c false/c string?) = "127.0.0.1"
  port : number? = 8000
  ssl-keys : (or/c false/c (cons/c path-string? path-string?))
   = #f

The other interesting part of serve/servlet is its ability to start up a server and immediately launch a browser at it. This is provided by serve/launch/wait.

It starts a server using the result of make-dispatcher as the dispatcher. make-dispatcher is supplied a semaphore that if posted, will cause the server to quit.

If launch-path is not false, then a browser is launched with that path appended to the URL to the server itself.

If banner? is true, then a banner is printed informing the user of the server’s URL.

The server listens on listen-ip and port port.

If ssl-keys is not false, then the server runs in HTTPS mode with (car ssl-keys) and (cdr ssl-keys) as paths to the certificate and private key.