On this page:
serve
serve/  ports
serve/  ips+  ports
serve/  web-config@
raw:  dispatch-server-connect@
make-ssl-connect@
do-not-return
3.1 Simple Single Servlet Servers
dispatch/  servlet
serve/  launch/  wait

3 Launching Servers

This module provides functions for launching dispatching servers.

procedure

(serve #:dispatch dispatch 
  [#:confirmation-channel confirmation-channel 
  #:connection-close? connection-close? 
  #:dispatch-server-connect@ dispatch-server-connect@ 
  #:tcp@ tcp@ 
  #:port port 
  #:listen-ip listen-ip 
  #:max-waiting max-waiting 
  #:initial-connection-timeout request-read-timeout 
  #:safety-limits safety-limits]) 
  (-> any)
  dispatch : dispatcher/c
  confirmation-channel : 
(or/c #f (async-channel/c
          (or/c exn? port-number?)))
   = #f
  connection-close? : boolean? = #f
  dispatch-server-connect@ : 
(unit/c (import)
        (export dispatch-server-connect^))
   = raw:dispatch-server-connect@
  tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@
  port : listen-port-number? = 80
  listen-ip : (or/c string? #f) = #f
  max-waiting : exact-nonnegative-integer? = 511
  request-read-timeout : timeout/c = 60
  safety-limits : safety-limits?
   = 
(make-safety-limits
 #:max-waiting max-waiting
 #:request-read-timeout request-read-timeout)
Constructs an appropriate dispatch-server-config*^, invokes the dispatch-server@, and calls its serve function.

If connection-close? is #t, then every connection is closed after one request. Otherwise, the client decides based on what HTTP version it uses.
The dispatch-server-connect@ argument supports the conversion of raw connections; for example, make-ssl-connect@ produces a unit to serve SSL by converting raw TCP ports to SSL ports; see also How do I set up the server to use HTTPS?.
The tcp@ argument supports replacing TCP connections with other kinds of connections (and was formerly recommended for SSL support). Beware that the server expects the tcp-accept operation from tcp@ to be effectively atomic; new connections are not accepted while tcp-accept is in progress.
The safety-limits argument supplies a safety limits value specifying the policies to be used while reading and handling requests. In the constructed dispatch-server-config*^, it is used directly as the safety-limits value and is also used by the read-request implementation.
The max-waiting and request-read-timeout arguments are supported for backwards compatability. If a safety-limits argument is given, the max-waiting and request-read-timeout arguments are ignored; otherwise, they are passed to make-safety-limits to construct the safety limits value. If neither max-waiting, request-read-timeout, nor safety-limits are given, the default safety limits value is equivalent to (make-safety-limits).
Here’s an example of a simple web server that serves files from a given path:
(define (start-file-server base)
  (serve
   #:dispatch
   (files:make
    #:url->path (make-url->path base)
    #:path->mime-type
    (lambda (path)
      #"application/octet-stream"))
   #:port 8080))

Changed in version 1.6 of package web-server-lib: Added the safety-limits argument and changed to use dispatch-server-config*^ instead of dispatch-server-config^: see compatability note. Corrected documented contracts for the max-waiting and request-read-timeout arguments.

procedure

(serve/ports 
  #:dispatch dispatch 
  [#:confirmation-channel confirmation-channel 
  #:connection-close? connection-close? 
  #:dispatch-server-connect@ dispatch-server-connect@ 
  #:tcp@ tcp@ 
  #:ports ports 
  #:listen-ip listen-ip 
  #:max-waiting max-waiting 
  #:initial-connection-timeout request-read-timeout 
  #:safety-limits safety-limits]) 
  (-> any)
  dispatch : dispatcher/c
  confirmation-channel : 
(or/c #f (async-channel/c
          (or/c exn? port-number?)))
   = #f
  connection-close? : boolean? = #f
  dispatch-server-connect@ : 
(unit/c (import)
        (export dispatch-server-connect^))
   = raw:dispatch-server-connect@
  tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@
  ports : (listof listen-port-number?) = (list 80)
  listen-ip : (or/c string? #f) = #f
  max-waiting : exact-nonnegative-integer? = 511
  request-read-timeout : timeout/c = 60
  safety-limits : safety-limits?
   = 
(make-safety-limits
 #:max-waiting max-waiting
 #:request-read-timeout request-read-timeout)
Calls serve multiple times, once for each port, and returns a function that shuts down all of the server instances.

Changed in version 1.6 of package web-server-lib: Added the safety-limits argument as with serve: see compatability note.

procedure

(serve/ips+ports 
  #:dispatch dispatch 
  [#:confirmation-channel confirmation-channel 
  #:connection-close? connection-close? 
  #:dispatch-server-connect@ dispatch-server-connect@ 
  #:tcp@ tcp@ 
  #:ips+ports ips+ports 
  #:max-waiting max-waiting 
  #:initial-connection-timeout request-read-timeout 
  #:safety-limits safety-limits]) 
  (-> any)
  dispatch : dispatcher/c
  confirmation-channel : 
(or/c #f (async-channel/c
          (or/c exn? port-number?)))
   = #f
  connection-close? : boolean? = #f
  dispatch-server-connect@ : 
(unit/c (import)
        (export dispatch-server-connect^))
   = raw:dispatch-server-connect@
  tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@
  ips+ports : (listof (cons/c (or/c string? #f) (listof listen-port-number?)))
   = (list (cons #f (list 80)))
  max-waiting : exact-nonnegative-integer? = 511
  request-read-timeout : timeout/c = 60
  safety-limits : safety-limits?
   = 
(make-safety-limits
 #:max-waiting max-waiting
 #:request-read-timeout request-read-timeout)
Calls serve/ports multiple times, once for each ip, and returns a function that shuts down all of the server instances.

Changed in version 1.1 of package web-server-lib: Added the #:dispatch-server-connect@ argument.
Changed in version 1.6: Added the safety-limits argument as with serve: see compatability note.

procedure

(serve/web-config@ 
  config@ 
  [#:dispatch-server-connect@ dispatch-server-connect@ 
  #:tcp@ tcp@]) 
  (-> void)
  config@ : (unit/c (import) (export web-config*^))
  dispatch-server-connect@ : 
(unit/c (import)
        (export dispatch-server-connect^))
   = raw:dispatch-server-connect@
  tcp@ : (unit/c (import) (export tcp^)) = raw:tcp@
Starts the Web Server with the settings defined by the given web-config*^ unit.

Changed in version 1.1 of package web-server-lib: Added the #:dispatch-server-connect@ argument.
Changed in version 1.6: Use web-config*^ rather than web-config^: see compatability note.

A default implementation of the dispatch server’s connection-conversion abstraction that performs no conversion.

Added in version 1.1 of package web-server-lib.

procedure

(make-ssl-connect@ server-cert-file 
  server-key-file) 
  (unit/c (import) (export dispatch-server-connect^))
  server-cert-file : path-string?
  server-key-file : path-string?
Constructs an implementation of the dispatch server’s connection-conversion abstraction for OpenSSL.

Added in version 1.1 of package web-server-lib.

procedure

(do-not-return)  none/c

This function does not return. If you are writing a script to load the Web Server you may want to call this functions at the end of your script.

3.1 Simple Single Servlet Servers

These functions optimize the construction of dispatchers and launching of servers for single servlets and interactive development.

procedure

(dispatch/servlet 
  start 
  [#:regexp regexp 
  #:stateless? stateless? 
  #:stuffer stuffer 
  #:manager manager 
  #:current-directory servlet-current-directory 
  #:responders-servlet-loading responders-servlet-loading 
  #:responders-servlet responders-servlet]) 
  dispatcher/c
  start : (request? . -> . response?)
  regexp : regexp? = #rx""
  stateless? : boolean? = #f
  stuffer : (stuffer/c serializable? bytes?) = default-stuffer
  manager : manager?
   = (make-threshold-LRU-manager #f (* 1024 1024 64))
  servlet-current-directory : path-string? = (current-directory)
  responders-servlet-loading : (url? any/c . -> . can-be-response?)
   = servlet-loading-responder
  responders-servlet : (url? any/c . -> . can-be-response?)
   = servlet-error-responder
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
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 servlet is run in the (current-namespace).
If a servlet fails to load, responders-servlet-loading is used. If a servlet errors during its operation, responders-servlet is used.

procedure

(serve/launch/wait make-dispatcher    
  [#:connection-close? connection-close?    
  #:launch-path launch-path    
  #:banner? banner?    
  #:listen-ip listen-ip    
  #:port port    
  #:ssl-cert ssl-cert    
  #:ssl-key ssl-key    
  #:max-waiting max-waiting    
  #:safety-limits safety-limits])  any
  make-dispatcher : (semaphore? . -> . dispatcher/c)
  connection-close? : boolean? = #f
  launch-path : (or/c #f string?) = #f
  banner? : boolean? = #f
  listen-ip : (or/c #f string?) = "127.0.0.1"
  port : number? = 8000
  ssl-cert : (or/c #f path-string?) = #f
  ssl-key : (or/c #f path-string?) = #f
  max-waiting : exact-nonnegative-integer? = 511
  safety-limits : safety-limits?
   = (make-safety-limits #:max-waiting max-waiting)
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. The make-dispatcher argument is called with 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 listen-ip is #f, then the server accepts connections to all of the listening machine’s addresses. Otherwise, the server accepts connections only at the interface(s) associated with the given string. For example, providing "127.0.0.1" (the default) as listen-ip creates a server that accepts only connections to "127.0.0.1" (the loopback interface) from the local machine.
If ssl-key and ssl-cert are not false, then the server runs in HTTPS mode with ssl-cert and ssl-key as paths to the certificate and private key.
If connection-close? is #t, then every connection is closed after one request. Otherwise, the client decides based on what HTTP version it uses.
The safety-limits argument supplies a safety limits value specifying the policies to be used while reading and handling requests.
The max-waiting argument is supported for backwards compatability. If a safety-limits argument is given, the max-waiting argument is ignored; otherwise, it is passed to make-safety-limits to construct the safety limits value. If neither max-waiting nor safety-limits are given, the default safety limits value is equivalent to (make-safety-limits).

Changed in version 1.6 of package web-server-lib: Added the safety-limits argument: see compatability note.