doc: Clarified the persistent handler convention slightly.

[ashd.git] / doc / ashd.doc

ashd(7)
=======

NAME
----
ashd - A Sane HTTP Daemon

DESCRIPTION
-----------

This document describes the architecture and protocol of ashd
technically. If you want a brief overview, please see the homepage at
<http://www.dolda2000.com/~fredrik/ashd/>.

The basic premise of ashd is that of standard Unix philosophy; it
consists of a number of different programs, each specialized to one
precise task, passing HTTP requests around to each other in a manner
akin to standard Unix pipelines. This document describes the set of
protocols and conventions used between such programs that allows them
to interoperate.

REQUESTS
--------

All requests within ashd are created by *htparser*(1), which speaks
HTTP with its clients, translates the requests it receives into ashd
format, and passes them to a specified handler program. The handler
program may choose to respond to the request itself, or pass it on to
another handler for further processing.

A request in ashd format consists of 4 structural parts:

HTTP method, URL and version::

	The HTTP header line information, exactly as specified by the
	client. That is, any escape sequences in the URL are passed
	around in non-processed form, since each program needs to
	handle escape processing in its own way.

The rest string::

	The 'rest string' (sometimes referred to as the 'point', in
	deference to Emacs parlance) is the part of the URL which
	remains to be processed. Each handler program is free to
	modify the rest string (usually, but not necessarily, by
	removing leading parts of it) before passing the request on to
	another handler. When *htparser*(1) initially constructs a
	request, it forms the rest string from the URL by stripping
	off the initial slash and the query parameters. In other
	words, a request to `/a/b/c?d=e` will be given the initial
	rest string `a/b/c`.

The HTTP headers::

	The HTTP headers are parsed and passed along with the request
	as they are, but *htparser*(1) itself, and some handler
	programs, add some more headers, prefixed with `X-Ash-`,
	and to safeguard any potentially sensitive such headers from
	forgery, *htparser*(1) strips any headers with that prefix
	from the incoming request.

The response socket::

	Along with the request information, a socket for responding is
	passed. A handler program that wishes to actually respond to a
	request needs only output a well-formed HTTP response on this
	socket and then close it. The details are covered below, but
	note that the socket is connected to *htparser*(1) rather than
	the client itself, and that *htparser* will do any transfer
	encoding that may be required for HTTP keep-alive. The
	response socket is also used for reading the request-body, if
	the client provides one.

HANDLERS
--------

Handler programs are started either by *htparser*(1) itself, or in
turn by other handler programs, and certain conventions are observed
in that process.

There are two basic types of handler programs, persistent and
transient, which determines the convention used in starting them. A
persistent program will continue running indefinitely, and handle any
amount of requests during its lifetime, while a transient program will
handle one request only and then exit. The convention of transient
programs was created mainly for convenience, since it is easier to
write such programs. The *htparser*(1) program will only start a
persistent program as the root handler.

A persistent handler program, when started, is passed a Unix socket of
SEQPACKET type on standard input (while standard output and error are
inherited from the parent process). Its parent program will then pass
one datagram per request on that socket, containing the above listed
parts of the request using the datagram format described below. By
convention, the handler program should exit normally if it receives
end-of-file on the socket.

A transient program, when started, has the response socket connected
to its standard input and output (standard error is inherited from the
parent process). It may be provided arbitrary arguments as supplied by
the program starting it, but the last three arguments are the HTTP
method, the raw URL and the rest string, in that order. The HTTP
headers are converted into environment variables by turning them into
uppercase, replacing any dashs with underscores, and prefixing them
with `REQ_`. For example, the HTTP `Host` header will be passed as
`REQ_HOST`. The HTTP protocol version is passed in an environment
variable called `HTTP_VERSION`. It is passed in full; i.e. as
`HTTP/1.1`, rather than just `1.1`.

The response socket, as mentioned above, is also used for reading the
request-body if the client provides one. For such purposes,
*htparser*(1) ensures that the reader sees end-of-file at the end of
the request-body, so that the reader (unlike in, for example, CGI)
does not have to worry about the Content-Length header and counting
bytes when reading.

To respond, the handler program needs to write an ordinary HTTP
response to the response socket. That is, one line containing the HTTP
version, status code and status text, followed by any number of lines
with headers, followed by an empty line, followed by the
response-body. Basic familiarity with HTTP should relieve this
document of detailing the exact format of such a response, but the
following points are noteworthy:

 * The HTTP version is actually ignored; it must simply be there for
   completeness.

 * In the header, Unix line endings are accepted; *htparser*(1) will
   still use CRLF line endings when passing the response to the
   client.

 * The response socket should be closed when the entire body has been
   written. *htparser*(1) itself will take care of anything needed for
   HTTP keep-alive, such as chunking. It is recommended, however, that
   the handler program provides the Content-Length header if it can be
   calculated in advance, since *htparser*(1) will not need to add
   chunking in such cases.

 * *htparser*(1) will not provide an error message to the client in
   case the response socket is closed before a complete response has
   been written to it, so a handler program should always provide an
   error message by itself if a request cannot be handled for some
   reason.

PROTOCOL
--------

The datagram format used for persistent handler programs is simply a
sequence of NUL-terminated strings. The datagram starts with the HTTP
method, the URL, the HTTP version and the rest string, in that
order. They are followed by an arbitrary number of string pairs, one
for each header; the first string in a pair being the header name, and
the second being the value. The headers are terminated by one instance
of the empty string.

Along with the datagram, the response socket is passed using the
SCM_RIGHTS ancillary message for Unix sockets. See *unix*(7),
*recvmsg*(2) and *sendmsg*(2) for more information. Each datagram will
have exactly one associated socket passed with it.

AUTHOR
------
Fredrik Tolf <fredrik@dolda2000.com>

SEE ALSO
--------
*htparser*(1), RFC 2616