docs.txt

-*- mode: markup; -*-

* Toot

Toot is intended to be a minimal web server on top of which more
fully-functional and user-friendly web servers can be used. Toot is
responsible for accepting network connections, reading and parsing
HTTP requests, and passing them off to a handler which can then
generate an HTTP response by writing content to a stream. Handlers can
also affect the response by setting HTTP response headers on the
request object they are handed.

** Generating responses

The simplest case:

   (start-server :port 8080 :handler (lambda (r) 'not-handled))

This creates a server that listens on port 8080 and replies to every
request with a bare-bones \code{404: Not Found} error page.

The \code{:handler} argument can be any object which can be passed as
the handler argument to the generic function:

   (defgeneric handle-request (handler request))

Out of the box Toot provides methods on \code{handle-request} that
specialize the first argument on \code{function} and \code{symbol} and
simply \code{funcall} the handler with the request as a single
argument. The \code{handle-request} method can either return a string
which is returned as the body of the response or can obtain a stream
by calling \code{send-headers} on the request object and write the
body of the response

** Customizing error pages


** Customizing logging


** Threading models






The only required argument to \code{start-server} is the
\code{:handler}—if \code{:port} is not specified the server will
default to 80 unless SSL configuration has been provided in which case
it will default to 443. However, normal user processes are typically
prevented from binding ports under 1024. On recent versions of Linux
you should be able to use \code{setcap 'cap_net_bind_service=+ep'
/path/to/program} to allow a given executable to bind low parts. To
use that technique, it’s probably best to build an executable of your
server with something like [Buildapp] and then \code{setcap} that
executable rather than setting it on your Lisp.



* Internals

** Acceptors

Manage a server socket and accept connections from clients. Each
acceptor has a \code{taskmaster} which is responsible for calling
\code{accept-connections} and \code{process-connection} for each
connection. Acceptors can optionally be configured with an SSL
certificate in which case they will provide an HTTPS, rather than
HTTP, listener.

** Requests

When it processes a connection, the acceptor reads a series of HTTP
requests for the client and turns them into \code{request} objects.
The \code{request} object holds all the information about the request
including the request-uri, method, http-version, all the headers (as
an alist with the header names as keywords), incoming cookies, and get
and post parameters. It also is used to hold information about the
response generated when the request is handled.

** Handlers

Handlers are responsible for taking a request and generating a
response. Toot invokes handlers via the generic function
\code{handle-request} which has two argument, the handler and the
request. Out of the box, Toot provides methods specializing the
handler argument on \code{function} and \code{symbol}, that funcall
the handler, which should denote a function of a single argument, with
the request object.

** Error page generators

When Toot needs to send an error page it uses the generic function
\code{generate-error-page} called on an error page generator, the
request, and with keyword arguments specifying the error and backtrace
if applicable.

** Taskmasters

Actually run the acceptors, either everything in one thread (a
single-threaded-taskmaster) or in a dedicated thread for
accept-connection and a new thread for each process-connection.

[Buildapp] <http://www.xach.com/lisp/buildapp/>