On this page:
4.1 Server Units
4.1.1 Signature
web-server^
serve
serve-ports
4.1.2 Unit
web-server-with-connect@
web-server@
4.2 Configuration Units
4.2.1 Signature
web-config*^
safety-limits
virtual-hosts
port
listen-ip
make-servlet-namespace
web-config^
max-waiting
initial-connection-timeout
4.2.2 Unit
configuration-table->web-config@
configuration-table-sexpr->web-config@
4.3 Configuration Table
default-configuration-table-path
configuration-table-sexpr?
sexpr->configuration-table
configuration-table->sexpr
read-configuration-table
write-configuration-table
4.4 Configuration Table Structure
configuration-table
host-table
host
responders
messages
timeouts
paths
4.5 Standard Responders
file-response
servlet-loading-responder
gen-servlet-not-found
servlet-error-responder
gen-servlet-responder
gen-servlets-refreshed
gen-passwords-refreshed
gen-authentication-responder
gen-protocol-responder
gen-file-not-found-responder
gen-collect-garbage-responder

4 Web Servers

A Web server is a unit with the web-server^ signature. The most common way to construct one is to provide a web-config^ unit to the web-server@ unit. The most common way to construct a web-config^ unit is to use configuration-table->web-config@ to produce one from a configuration table file, such as the one that is shipped with Racket in default-configuration-table-path.

4.1 Server Units

signature

web-server^ : signature

procedure

(serve [#:confirmation-channel confirmation-ach])  (-> any)

  confirmation-ach : 
(or/c #f (async-channel/c
          (or/c exn? port-number?)))
 = #f
The same as serve from dispatch-server^. The dispatch-server^ signature is an alias for web-server^.

procedure

(serve-ports ip op)  any

  ip : input-port?
  op : output-port?
Asynchronously serves a single connection represented by the ports ip and op.

 (require web-server/web-server-unit)
  package: web-server-lib

Uses the web-config*^ to construct a dispatcher/c function that sets up one virtual host dispatcher, for each virtual host in the web-config*^, that sequences the following operations:

Using this dispatcher/c, it loads a dispatching server that provides serve and serve-ports functions that operate as expected.

Added in version 1.1 of package web-server-lib.
Changed in version 1.6: Use web-config*^ rather than web-config^. See compatability note.

value

web-server@ : 
(unit/c (web-config*^ tcp^)
        (web-server^))

Changed in version 1.6 of package web-server-lib: Use web-config*^ rather than web-config^. See compatability note.

4.2 Configuration Units

signature

web-config*^ : signature

Contains the following identifiers.

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

A safety limits value specifying the policies to be used while reading and handling requests.

value

virtual-hosts : (string? . -> . host?)

Contains the configuration of individual virtual hosts.

Specifies the port to serve HTTP on.

value

listen-ip : (or/c #f string?)

Passed to tcp-listen.

signature

web-config^ : signature

NOTE: This signature is deprecated; use web-config*^, instead.

For backwards compatability, web-config^ extends web-config*^ and uses define-values-for-export to define safety-limits as:
(make-safety-limits
 #:max-waiting max-waiting
 #:request-read-timeout initial-connection-timeout)

Changed in version 1.6 of package web-server-lib: Deprecated in favor of web-config*^. See compatability note.

Passed to make-safety-limits.
Passed to make-safety-limits as its #:request-read-timeout argument.

Changed in version 1.6 of package web-server-lib: Loosened contract for consistency with make-safety-limits.

procedure

(configuration-table->web-config@ 
  path 
  [#:port port 
  #:listen-ip listen-ip 
  #:make-servlet-namespace make-servlet-namespace]) 
  (unit/c (import) (export web-config^))
  path : path-string?
  port : (or/c false/c port-number?) = #f
  listen-ip : (or/c false/c string?) = #f
  make-servlet-namespace : make-servlet-namespace/c
   = (make-make-servlet-namespace)
Reads the S-expression at path and calls configuration-table-sexpr->web-config@ appropriately.

procedure

(configuration-table-sexpr->web-config@ 
  sexpr 
  [#:web-server-root web-server-root 
  #:port port 
  #:listen-ip listen-ip 
  #:make-servlet-namespace make-servlet-namespace]) 
  (unit/c (import) (export web-config^))
  sexpr : list?
  web-server-root : path-string?
   = (directory-part default-configuration-table-path)
  port : (or/c false/c port-number?) = #f
  listen-ip : (or/c false/c string?) = #f
  make-servlet-namespace : make-servlet-namespace/c
   = (make-make-servlet-namespace)
Parses sexpr as a configuration-table and constructs a web-config^ unit.

4.3 Configuration Table

This module provides functions for reading, writing, parsing, and printing configuration-table structures.

The default configuration table S-expression file.

Equivalent to list?.

This function converts a configuration-table from an S-expression.

This function converts a configuration-table to an S-expression.

The configuration table format is:
`((port ,integer?)
  (max-waiting ,exact-integer?)
  (initial-connection-timeout ,integer?)
  (default-host-table
    ,host-table-sexpr?)
  (virtual-host-table
   (list ,symbol? ,host-table-sexpr?)
   ...))
where a host-table-sexpr is:
`(host-table
  (default-indices ,string? ...)
  (log-format ,symbol?)
  (messages
   (servlet-message ,path-string?)
   (authentication-message ,path-string?)
   (servlets-refreshed ,path-string?)
   (passwords-refreshed ,path-string?)
   (file-not-found-message ,path-string?)
   (protocol-message ,path-string?)
   (collect-garbage ,path-string?))
  (timeouts
   (default-servlet-timeout ,integer?)
   (password-connection-timeout ,integer?)
   (servlet-connection-timeout ,integer?)
   (file-per-byte-connection-timeout ,integer?)
   (file-base-connection-timeout ,integer))
  (paths
   (configuration-root ,path-string?)
   (host-root ,path-string?)
   (log-file-path ,path-string?)
   (file-root ,path-string?)
   (servlet-root ,path-string?)
   (mime-types ,path-string?)
   (password-authentication ,path-string?)))
In this syntax, the 'messages paths are relative to the 'configuration-root directory. All the paths in 'paths except for 'servlet-root are relative to 'host-root (other than 'host-root obviously.) The 'servlet-root path is relative to 'file-root.
Allowable 'log-formats are those accepted by log-format->format.
Note: You almost always want to leave everything in the 'paths section the default except the 'host-root.

This function reads a configuration-table from path.

procedure

(write-configuration-table ctable path)  void

  ctable : configuration-table?
  path : path-string?
This function writes a configuration-table to path.

4.4 Configuration Table Structure

This module provides the following structures that represent a standard configuration (see Server Units) of the Web Server . The contracts on this structure influence the valid types of values in the configuration table S-expression file format described in Configuration Table.

struct

(struct configuration-table (port
    max-waiting
    initial-connection-timeout
    default-host
    virtual-hosts)
    #:extra-constructor-name make-configuration-table)
  port : port-number?
  max-waiting : exact-nonnegative-integer?
  initial-connection-timeout : natural-number/c
  default-host : host-table?
  virtual-hosts : (listof (cons/c string? host-table?))

struct

(struct host-table (indices log-format messages timeouts paths)
    #:extra-constructor-name make-host-table)
  indices : (listof string?)
  log-format : symbol?
  messages : messages?
  timeouts : timeouts?
  paths : paths?

struct

(struct host (indices
    log-format
    log-path
    passwords
    responders
    timeouts
    paths)
    #:extra-constructor-name make-host)
  indices : (listof string?)
  log-format : symbol?
  log-path : (or/c false/c path-string?)
  passwords : (or/c false/c path-string?)
  responders : responders?
  timeouts : timeouts?
  paths : paths?

struct

(struct responders (servlet
    servlet-loading
    authentication
    servlets-refreshed
    passwords-refreshed
    file-not-found
    protocol
    collect-garbage)
    #:extra-constructor-name make-responders)
  servlet : (url? any/c . -> . response?)
  servlet-loading : (url? any/c . -> . response?)
  authentication : (url? (cons/c symbol? string?) . -> . response?)
  servlets-refreshed : (-> response?)
  passwords-refreshed : (-> response?)
  file-not-found : (request? . -> . response?)
  protocol : (url? . -> . response?)
  collect-garbage : (-> response?)

struct

(struct messages (servlet
    authentication
    servlets-refreshed
    passwords-refreshed
    file-not-found
    protocol
    collect-garbage)
    #:extra-constructor-name make-messages)
  servlet : string?
  authentication : string?
  servlets-refreshed : string?
  passwords-refreshed : string?
  file-not-found : string?
  protocol : string?
  collect-garbage : string?

struct

(struct timeouts (default-servlet
    password
    servlet-connection
    file-per-byte
    file-base)
    #:extra-constructor-name make-timeouts)
  default-servlet : number?
  password : number?
  servlet-connection : number?
  file-per-byte : number?
  file-base : number?

struct

(struct paths (conf
    host-base
    log
    htdocs
    servlet
    mime-types
    passwords)
    #:extra-constructor-name make-paths)
  conf : (or/c false/c path-string?)
  host-base : (or/c false/c path-string?)
  log : (or/c false/c path-string?)
  htdocs : (or/c false/c path-string?)
  servlet : (or/c false/c path-string?)
  mime-types : (or/c false/c path-string?)
  passwords : (or/c false/c path-string?)

4.5 Standard Responders

This module provides some functions that help constructing HTTP responders. These functions are used by the default dispatcher constructor (see Server Units) to turn the paths given in the configuration-table into responders for the associated circumstance.

procedure

(file-response http-code    
  short-version    
  text-file    
  header ...)  response?
  http-code : natural-number/c
  short-version : string?
  text-file : string?
  header : header?
Generates a response? with the given http-code and short-version as the corresponding fields; with the content of the text-file as the body; and, with the headers as, you guessed it, headers.

This does not cause redirects to a well-known URL, such as "conf/not-found.html", but rather use the contents of "not-found.html" (for example) as its contents. Therefore, any relative URLs in text-file are relative to whatever URL file-response is used to respond to. Thus, you should probably use absolute URLs in these files.

procedure

(servlet-loading-responder url exn)  response?

  url : url?
  exn : exn?
Gives exn to the current-error-handler and response with a stack trace and a "Servlet didn’t load" message.

procedure

(gen-servlet-not-found file)  ((url url?) . -> . response?)

  file : path-string?
Returns a function that generates a standard "Servlet not found." error with content from file.

procedure

(servlet-error-responder url exn)  response?

  url : url?
  exn : exn?
Gives exn to the current-error-handler and response with a stack trace and a "Servlet error" message.

procedure

(gen-servlet-responder file)

  ((url url?) (exn any/c) . -> . response?)
  file : path-string?
Prints the exn to standard output and responds with a "Servlet error." message with content from file.

procedure

(gen-servlets-refreshed file)  (-> response?)

  file : path-string?
Returns a function that generates a standard "Servlet cache refreshed." message with content from file.

procedure

(gen-passwords-refreshed file)  (-> response?)

  file : path-string?
Returns a function that generates a standard "Passwords refreshed." message with content from file.

procedure

(gen-authentication-responder file)

  ((url url?) (header header?) . -> . response?)
  file : path-string?
Returns a function that generates an authentication failure error with content from file and header as the HTTP header.

procedure

(gen-protocol-responder file)  ((url url?) . -> . response?)

  file : path-string?
Returns a function that generates a "Malformed request" error with content from file.

procedure

(gen-file-not-found-responder file)

  ((req request?) . -> . response?)
  file : path-string?
Returns a function that generates a standard "File not found" error with content from file.

procedure

(gen-collect-garbage-responder file)  (-> response?)

  file : path-string?
Returns a function that generates a standard "Garbage collection run" message with content from file.