Semi-Internal Functions

The following functions expose more of the Web server for use by the development environment. They are not intended for general use. They may change at anytime or disappear entirely. These are just for the developers.

11.1  Miscellaneous

server-loop

   custodian (-> iport oport) (-> void) -> void
   (define (server-loop custodian tcp-listener config initial-timeout) ···)

custodian
The parent custodian for servlets.
tcp-listener
Where requests arrive.
config
Encapsulates most of the state of the server.
initial-timeout
The number of seconds before timing out connections.

make-config

   (string -> host) (hash-table-of sym script) (unit servlet-sig -> response) (hash-table-of sym servlet-instance) -> config
   (define (make-config hosts scripts instances access) ···)

host-table
string -> host

Maps host names to hosts

script-table
(hash-table-of sym script)

Maps servlet names to servlet units

script
(unit servlet^ -> response)

Represents a servlet that is invoked on each request

instance-table
(hash-table-of sym servlet-instance)

Maps the path part of a URL to the running servlet.

access-table
(hash-table-of sym (string sym string -> (union \#f str)))

Maps host names to functions that accept a protection domain, a user name, and a password and either return \#f if access is not denied (i.e. is accessible) or a string prompting for a particular password (i.e. ``Course Grades'').

servlet-instance
(make-servlet-instance nat channel (hash-table-of sym (continuation request)))

The natural-number counts the continuations suspended by this servlet. The channel communicates HTTP requests from the connection thread to the suspended servlet. The hash-table maps parameter parts of URLs to suspended continuations.

11.2  Starting the Server from a Program

Requiring the library web-server.ss, via

(require (lib "web-server.ss" "web-server"))

provides the serve function, which starts the server with more configuration options.

serve

   configuration [natural-number (union string #f)] -> (-> void)
   (define (serve configuration . port ip-address) ···)

The serve function starts the Web server just like the launcher does, but the configuration argument supplies the server's settings. The optional port argument overrides the port supplied by the configuration. The optional ip-address binds the server to that address.

The result of invoking serve is a function of no arguments that shuts down the server.

serve

   (opt->* (configuration?) ((and/f number? integer? exact? positive?) (union string? false?) (make-mixin-contract frame%)) ((-> void?) (any? . -> . (union false? string?)) (any? . -> . (union false? string?)) (any? . -> . string?) (-> (union false? (is-a?/c frame%))) (-> (is-a?/c frame%))))
   (define (serve configuration . frame) ···)

In addition, this serve function accepts another optional argument. This argument is mixed into the frame% class created by the internal browser. The frame is then instantiated with one argument: the URL to visit.

11.3  Constructing Configurations

Constructing configurations requires another library.

(require (lib "configuration.ss" "web-server"))

load-configuration

   string -> configuration
   (define (load-configuration path) ···)

This function accepts a path to a configuration file and returns a configuration that serve accepts. The configuration tool can create configuration files, as explained in the section titled ``The Configuration Tool''. Configuration files can also be created by hand, as described in the section titled ``Configuration Syntax''.

11.4  Monitoring the Server

Requiring the library monitor-web-server.ss, via

(require (lib "monitor-web-server.ss" "web-server"))

provides the functions:

poke-web-server

   channel string nat nat -> result
   (define (poke-web-server channel server port timeout-seconds) ···)

The poke-web-server procedure takes a channel on which the results will come in, a server name to test, a port on that server to test, and a timeout (in seconds). The procedure returns immediately. The channel passed to the procedure will receive at least one result within (timeout-seconds + epsilon), for some reasonable epsilon.

A result is one of:

where server-name and msg are strings, server-port and timeout-seconds are numbers, and exn is an exception.

result-message

   result -> string
   (define (result-message result) ···)

The result-message procedure takes a result and produces a multi-line string suitable for inclusion in an error log or an email message.

11.4.1  Example

Here's a simple piece of code which checks the PLT download server:

(require (lib "monitor-web-server.ss" "web-server"))
(let ([result-channel (make-channel)]
      [server-name "download.plt-scheme.org"]
      [server-port 80])
    (poke-web-server result-channel server-name server-port 10)
    (let ([result (channel-get result-channel)])
      (match result
           [`(ok) (void)]
           [else (printf (result-message result))])))

To have this done automatically, see the section titled ``Monitoring the Server'' or Monit.