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.