4 Web Servers

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)
	package: web-server-lib

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

value
web-server-with-connect@
:
(unit/c (web-config*^ tcp^ dispatch-server-connect^)
(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.

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^))

Like web-server-with-connect@, but using raw:dispatch-server-connect@.

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

4.2 Configuration Units🔗ℹ

(require web-server/web-config-sig)
	package: web-server-lib

signature
web-config*^ : signature

Contains the following identifiers.
Added in version 1.6 of package web-server-lib.
value
safety-limits : safety-limits?
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.
value
port : port-number?
Specifies the port to serve HTTP on.
value
listen-ip : (or/c #f string?)
Passed to tcp-listen.
value
make-servlet-namespace : make-servlet-namespace/c
Passed to servlets:make through make-default-path->servlet.

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.
value
max-waiting : exact-nonnegative-integer?
Passed to make-safety-limits.
value
initial-connection-timeout : timeout/c
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.

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

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)
	package: web-server-lib

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)
	package: web-server-lib

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🔗ℹ

(require web-server/configuration/responders)
	package: web-server-lib

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.

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