Scieneer Common Lisp 1.3.9 online documentation

http:make-server &key service-function service-headers-function log-function enable-keep-alive-p enable-content-compression-p stream-timeout stream-expiration stream-rate idle-timeout linger-timeout maximum-connections maximum-connection-requests maximum-headers-size maximum-body-size task-queue queue-task protocol protocol-major protocol-minor[Function]

Make and a new HTTP server object. Connection listeners may be added to the the server by http:start-http-listener, and http:start-https-listener. When a request is received it is read and packaged into a http:request object, and the service-function called with the server and request as arguments. A service-function must be defined and must return a http:response object which is also immutable.

An optional service-headers-function may be defined which is called after reading the request headers but before reading the request body. The server object and the partial request object are passed as arguments. This function may modify the request object stream timeout and expiration time, and set the maximum number of bytes permitted when reading the body. This function may also return a response which is sent to the client immediately without reading the body.

After preparing and sending a response, the log-function, if any, is called. See http:server-log-function for the function arguments.

When the enable-keep-alive-p argument is true, the connection is kept open if appropriate after sending a response for up to the idle-timeout. A connection is forced to close once the optional maximum-connection-requests limit is reached. The server will close idle connections prematurely if the server maximum-connections limit is reached to give priority to new connection requests, and this strategy makes it practical to keep idle connections alive for a relatively long period without blocking new requests.

If an individual stream operation is not completed within the stream-timeout then the request will be aborted and the stream closed which can protect against communication with the client stopping. If the time elapsed since the start of a request exceeds the stream-expiration time then the request will also be aborted and the stream closed which can protect against slow communication with the client even if data is trickling through. When nil the time is unlimited. The timeout and expiration time may be set per-request by the service-headers-function.

The stream-rate is the default target rate in bytes per second at which responses are sent. If this is not supplied or nil then the default target rate is unlimited. The rate may be controlled for individual responses by providing a rate for a response, see http:make-response.

The optional maximum-headers-size limits the size in bytes of the request headers, and the optional maximum-body-size limits the size in bytes of the request body. These limits may be specified to manage denial-of-service attacks and broken clients. The maximum request body size may also be set per-request by the service-headers-function.

The response content may be automatically compressed, using gzip compression, before sending if enable-content-compression-p is true, but only text/html and text/plain context may be automatically compressed.

The default server protocol is HTTP/1.1, but this may be overridden by specifying the protocol string, the protocol-major and protocol-minor numbers. The only other meaningful values are HTTP/1.0, 1, and 0 respectively.

The lisp system process may have a soft and hard system limit on the number of open file descriptors and when the server is activated, by adding a listener, the maximum-connections limit is compared with the system limits for the process. The soft system limit is increased if necessary and if the hard limit is reached then a warning is be printed and the server maximum-connections is reduced.

When a task-queue is specified, the listeners for this server may use a pool of threads to process each connection. If the task-queue is nil then the listeners will create a new thread to process each connection. The task queue avoids the overhead of creating a new thread for each connection, and the task queue can keep the connection resource usage in bounds. If a task-queue is not specified then a default queue is created with a maximum of 32 threads and a queue length of 300 connections. The queue-task function will be called with the task-queue and a function as arguments.

A default server object is provided and stored in the http:*default-server* variable, but it is not activated until a listener is started.