What follows is a description of the http extension, which is separated into three sub-extensions: http-client (HTTP client functionality), http-server (serving HTTP requests) and http-utils (utility functions common to client and server code).

If you want to run a web-server, you should also take a look at the more featureful spiffy extension.

Sends an HTTP request represented by REQUEST, which may either be a HTTP request object, or a string that specifies an URL. The request is sent to it's destination and four values are returned: a string containing the first line of the response received from the server, an a-list that maps HTTP headers to values (strings) and the input- and output-port of the connection. Note that the connection is still open, and the returned ports can be passed in subsequent invocations of http:send-request to achieve a persistent connection. The ports are closed automatically, if no longer referenced.

If an URL is given instead of a request record, a request is sent of the form

Sends a GET request represented by REQUEST, which may be a string (an URL) or a HTTP request object, and returns a string containing the body of the servers response. The REQUEST keeps a Cookie header that is set by Set-Cookie headers in a response, unsafely (hack), regardless of the storing policy. Be aware of it when reusing REQUEST.

Sends a POST request represented by REQUEST, which may be a string (URL) or a HTTP request object, and returns a string containing the body of the server response. ARGUMENTS may be one of several forms depending on the value of the Content-Type attribute. If ARGUMENTS is unspecified, the body will be blank (i.e., a headers-only request). DELIM is an arbitrary separator string defaulting to the null-string. The behaviour of DELIM is dependent on Content-Type. HEADERS should be either null or a list composed of (ATTRIBUTE . VALUE) pairs. Connection and Content-Type, if unspecified, will be added automatically. Attributes are not case sensitive. Any attributes explicitly given in HEADERS are used, even if normally autogenerated. CTYPE is the Content-Type header attribute, and defaults to application/x-www-form-urlencoded. http:POST has special handlers for several values of Content-Type to simplify creation of the body, as given below:

Content-Type

Handler

application/x-www-form-urlencoded

ARGUMENTS may be a string or a list. The list may contain either (NAME . VALUE) pairs or strings of the form "name=value". The message body is generated as "name1=val1&name2=val2...". DELIM is ignored.

multipart/form-data

ARGUMENTS may be a string or a list. DELIM is used as the boundary between multipart sections, or defaults to ----chicken-scheme---- if absent. DELIM is automatically added to the Content-Type header as the value of the boundary attribute. Each element of the ARGUMENTS top-level list generates a single multipart segment, and must be composed of elements of the following types:

NAME

name attribute set to NAME. Body is empty.

(NAME . VALUE)

name attribute set to NAME. Body set to VALUE.

(NAME (ATTRIB . AVAL)... VALUE)

name attribute set to NAME. Every (ATTRIB . AVAL) pair is added to the segment header as ATTRIB="AVAL", separated by semicolons. If ATTRIB ends with a colon, it is added to the body to allow metadata for file transmission. VALUE is appended to the body after attributes are processed, and must NOT be a pair.

everything else

ARGUMENTS may be a string or a list of strings. Lists of strings are concatenated with DELIM as a separator.

The above alterations are performed only when ARGUMENTS is a list. If given as a string, the body is set to the string value without any alteration. All values other than strings or lists generate an error.

The server maps URLs to resource-handlers, which are procedures that process incoming client-requests. A resource-handler is responsible for generating a response by writing output to the value of (current-output-port).

The data contained in a client-request is parsed by a so-called content-parser, which is a procedure that reads the request-body from the port given by (current-input-port). Content-types are encoded as symbols.

A parser for application/x-www-form-urlencoded is predefined, other content-parsers have to be defined by application-code using the procedure http:content-parser, or the default parser will be invoked (which reads the content as a plain string).

The content-parser for text returns the request-body as a string. The content-parser for urlencoded data returns the request-body as an a-list that maps variables to strings.

Creates and returns a server-procedure. NAME defaults to something silly, PROTOCOL to #f (ignored), BACKLOG to 40 and ACCEPT to #f. INIT should be a procedure of no arguments that will be called after the networking initialisation has taken place (specifically, after the invocation of tcp-listen).

To run the server-loop, invoke the returned procedure, which takes an optional boolean argument (passing #t will generate debugging output). PORTNUMBER, BACKLOG, and ACCEPT are directly passed on to tcp-listen (see Unit tcp for more information about those parameters).

Writes a HTTP response header for request REQ to PORT, containing the server-name. CODE and MSG default to 200 and OK, respectively. The optional ALIST may contain pairs with header-names and -values. If given, PROTOCOL specifes the HTTP protocol to use for the reply, which should be a symbol (either HTTP/1.0 or HTTP/1.1) and defaults to the protocol given in http:make-server.

Reads ot sets the handler procedure PROC for the request-method METHOD (which should be a symbol). PROC should accept one argument, a request-object. During execution of the handler, the current input- and output ports are bound to ports connected to the client.

Defines a new resource for URL (which may be a string, a symbol or a list of strings/symbols). HANDLER should be a procedure of two arguments: a request structure, and an a-list mapping urlencoded arguments to values.

During execution of the handler the current input- and an output-ports are bound to ports communicating with the client.

Contains a procedure that will be called when an HTTP error-response should be generated. The procedure is called with the error-code and message and should return a string containing HTML that will be sent in the body of the error-response.

A procedure that will be called upon completion of a HTTP request. The procedure will be called with two arguments: the request object and the IP address of the client. The default value of this parameter does nothing.

A procedure that allows arbitrary transformations of the URL part of each incoming request. The procedure is called with a single argument (the URL string) and should return the same URL, or a transformed one. The default transformation returns the original url unchanged.

In case http:url-transformation is not useful (for example, when the need for a rewrite can only be discovered at a later stage in the request or when more than just the URL needs to be rewritten (for example when a header or POST data needs rewriting), you can use http:restart-request to restart the entire request processing. The REQUEST object should be the request that the http server sees as if it were sent by the client.

Be very careful: restarting requests can lead to infinite loops, so test your restart logic well.

Accessor procedures for the components of a HTTP request structure. URL is a string, METHOD and PROTOCOL are symbols, BODY is either #f or a string and ATTRIBUTES is an a-list where each pair contains an attribute string and a value string.

Accessor procedure to get the value of ATTRIB in REQUEST. If ATTRIB is not present in request, DEFAULT is returned. The search is case-insensitive. Note that this only returns the value; the attribute name is NOT returned.

[procedure] (http:request-attribute-add! REQUEST ATTRIB AVAL)

Adds ATTRIB to REQUEST's attribute list with its value set to AVAL. If ATTRIB already appears in the list (case-insensitive), its value is set to AVAL and it retains its position in the list; otherwise, the (ATTRIB . AVAL) pair is added to the end.

[procedure] (http:request-attribute-del! REQUEST ATTRIB)

Removes ATTRIB from the attribute list in REQUEST, if it exists (case-insensitive search). The order of the attribute list is not altered aside from the removal. It is not an error for ATTRIB to not appear in the list.

Reads MIME type headers from PORT until end of file is reached or a line is not a valid MIME header and returns an a-list where each pair holds the header (converted to lowercase) and the value (both strings).

2.8 Implemented a fix to prevent sending of the port number in Host header lines when the default port is used. This causes better interoperability with some broken webservers (reported by Drew Hess). Added error-handling to http-client for the case when remote closes connection unexpectedly. Added better handling for HTTP/1.1 server - HTTP/1.0 client interaction.

2.7 Implemented http:restart-request and fixed a bug that caused a 'bad rqust' when empty headers were sent (reported by Drew Hess)

2.5.2 Fixed HTTP version mismatch when no explicit version was set by the server and the client sent HTTP/1.0, changed Connection: keep-alive to Connection: close when http:force-close was #t and using HTTP/1.0.

Copyright (c) 2003, Felix L. Winkelmann
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following
conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following
disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the author nor the names of its contributors may be used to endorse or promote
products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS
OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.