Extending CL-HTTP

Computing Responses

Dynamically computed Web pages are the forte of this server. These computed responses are written in LISP, which supersedes legacy CGI interfaces. See the documentation on computing responses.

Exporting CGI Scripts

The server provides a Common Gateway Interface via the macro http:with-cgi-environment that is useful when writing new export methods that need to invoke invoke conventional scripts outside of Common Lisp via the CGI 1.1 standard. These export methods should be specialization of the URL class URL:COMPUTED-URL.

Defining New Mime Types

In general New MIME types is needed primarily when you want to export a new MIME content type, either from static files or dynamic computations. http:define-url-export-type automatically defines new MIME types when it sets up a new export types. Here is an example:

(http:define-url-export-type
	:shockwave-file	;Export Type :dir ;Primary
	Extension (:application :x-director)	;MIME
	Type :copy-mode :binary	;Binary Content
	:alternate-extensions (:dcr))	;Other
	Extensions

When no corresponding export type is required, you may use http::define-mime-content-type.

Writing New Export Methods

In order to add new export types, you need to write methods for the generic functions:

EXPORT-URL: This method interns the URL and initializes it. Don't forget to update the documentation string on the generic function definition to explain how to use your new export type/
WRITE-DOCUMENT-HEADERS: This method is invoked to handle the HTTP :HEAD operation. It writes the HTTP headers describing the document over the HTTP stream back to the client.
WRITE-DOCUMENT: This method is invoked to handle the HTTP :GET operation. It writes the document body and headers over the HTTP stream back to the client.

A new export type is appropriate when existing ones cannot do the job you require. It is important to consider whether and existing export type could be generalized to meet your requirements before embarking on a new export type. If your new operation is not idempotent (i.e., side effects on the server), you should define method for POST-DOCUMENT instead. Earlier versions of the HTTP specification included additional methods, like PUT, DELETE, and LINK, which may be reinstated when their application becomes apparent.

Defining New Log Classes

A number of logging choices are available by merely setting http:*log-access-log-class* in your CL-HTTP configuration file. When these do not suffice, CL-HTTP logging can be easily extended. A standard log object contains various mixins that perform different actions. For example, http:basic-file-logging-mixin provides the functionality to write log entries without blocking HTTP connections, and therefore, without slowing the server down to disk speeds. http:log-counters-mixin keeps track of server statistics whereas http:log-notification-mixin writes notifications to the log window. Typically, an application will run one of the standard log classes, such as http:common-file-log. Extensions will want to write different information to a file. In this case, remove notification or counter mixins that duplicate other logs you are running, and follow the procedure below:

Define a new log class
Copy one of the existing definitions such as http:extended-common-file-log. After renaming the calss, provide your own mixin class to which defines your own methods to write entries:
- HTTP:LOG-ENTRY-WRITER is the non-blocking method that snapshots the state of an HTTP connection and returns a closure to write the entry to the log file.
- HTTP:WRITE-ACCESS-LOG-ENTRY is the blocking method that writes the information to other streams.
Run a new log instance on a port
Add a call to http:intern-access-log to your CL-HTTP configuration file. This will install an instance of your log class on the specified port.

If you decide to make your custom log the default, instead of using http:intern-access-log, you can set http:*log-access-log-class* to your new class in your CL-HTTP configuration file.

A number of variations are possible. The class http:custom-notification-log simplifies the task of writing a log class that notifies the console. http:examples;log-window.lisp defines a log object that notifies a remote Web browser. In some cases, you may need to define methods for HTTP:log-server-access. Be sure to check the documentation for related log operators [External Internal].

John C. Mallery -- jcma@ai.mit.edu
M.I.T. Artificial Intelligence Laboratory