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

(require web-server/web-server-sig)

signature
web-server^ : signature

procedure
(serve) → (-> void)
Runs the server and returns a procedure that shuts down the server.
procedure
(serve-ports ip op) → void
ip : input-port?
op : output-port?
Serves a single connection represented by the ports ip and op.

(require web-server/web-server-unit)

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

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:

Logs the incoming request with the given format to the given file
Performs HTTP Basic Authentication with the given password file
Allows the "/conf/refresh-passwords" URL to refresh the password file.
Allows the "/conf/collect-garbage" URL to call the garbage collector.
Allows the "/conf/refresh-servlets" URL to refresh the servlets cache.
Executes servlets mapping URLs to the given servlet root directory under htdocs.
Serves files under the "/" URL in the given htdocs directory.

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

4.2 Configuration Units

(require web-server/web-config-sig)

signature
web-config^ : signature

Provides contains the following identifiers.

value
max-waiting : integer?
Passed to tcp-accept.
value
virtual-hosts : (string? . -> . host?)
Contains the configuration of individual virtual hosts.
value
initial-connection-timeout : integer?
Specifies the initial timeout given to a connection.
value
port : port-number?
Specifies the port to serve HTTP on.
value
listen-ip : (or/c false/c string?)
Passed to tcp-listen.
value
make-servlet-namespace : make-servlet-namespace/c
Passed to servlets:make through make-default-path->servlet.

(require web-server/web-config-unit)

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

(require web-server/configuration/configuration-table)

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

value
default-configuration-table-path : path?

The default configuration table S-expression file.

value
configuration-table-sexpr? : (any . -> . boolean?)

Equivalent to list?.

procedure
(sexpr->configuration-table sexpr) → configuration-table?
sexpr : configuration-table-sexpr?

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

procedure
(configuration-table->sexpr ctable)
→ configuration-table-sexpr?
ctable : configuration-table?

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.

procedure
(read-configuration-table path) → configuration-table?
path : path-string?

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

(require web-server/configuration/configuration-table-structs)

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 : natural-number/c
  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

(require web-server/configuration/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.

top ← prev up next →

1	Dispatching Server
2	Dispatchers
3	Launching Servers
4	Web Servers
5	Internal APIs
6	Troubleshooting and Tips
	Index

4.1	Server Units
4.2	Configuration Units
4.3	Configuration Table
4.4	Configuration Table Structure
4.5	Standard Responders