4 Web Servers

▼ |  | Web Server: HTTP Server

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

► | 4 | Web Servers

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

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

top contents ← prev up next →

## 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.
top contents ← prev up next →