Chapter 11

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  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.2  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''.

load-configuration-sexpr

   sexpr -> configuration
   (define (load-configuration-sexpr table) ···)

This function accepts a table S-expression and returns a configuration that serve accepts. This function is used by load-configuration, but may be more convenient for programmatic server configurations.

11.3  Monitoring the Server

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

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

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:

• `(fail ,server-name ,server-port ,msg)

• `(timeout ,server-name ,server-port ,timeout-seconds)

• `(exn ,server-name ,server-port ,exn)

• `(ok)

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.3.1  Example

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

(require (lib "monitor-poke-web-server.ss" "web-server" "private"))
(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.