= Httpd =

Httpd supervises established connections by:

1. Routing connections to one of a collection of [HttpdWorker] entities to parse the protocol.

2. Accepting and dispatching protocol requests parsed by [HttpdWorker] entities.

3. Processing parsed requests by:
   1. Filtering sites banned by the [Block] module
   2. Intercepting [Honeypot]-trapped connections
   3. Invoking optional callout script ($rqCallOut)
   4. Checking [Cache] and delivering cached content (if any)
   5. Dispatching to the script specified by '''-dispatch''' element of request, by default the value of ''dispatch'' configured variable, by default [Backend].

Httpd also maintains an [Activity] register of current connections.

== Architecture ===

Httpd maintains a pool of [HttpdWorker]s to which it distributes newly connected incoming sockets.

The workers completely supervise connections as HTTP1.1 pipelines, indicating when a complete request has been parsed, and when a connection has disconnected.

Httpd processes parsed requests by means of [Cache], [Block] and [Honeypot] without reference to the [Backend] to which it dispatches otherwise unhandled requests.

== Processing Model ==

Httpd supports two different process models: 

[HttpdSingle]: [HttpdWorker]s occupy the same thread as Httpd, in multiple interpreters each of which may handle multiple connections.  [[package require HttpdSingle]] selects this model.
[HttpdThread]: Each [HttpdWorker] runs in its own thread, handling multiple connections.  [[package require HttpdThread]] selects this model.

== configuration ==

Any of the variables which control Httpd's behavior may be set by [[Httpd configure]], which expects as key-value strings.

script: literal script to be loaded into each Worker.  (default: contents of [HttpdWorker].tcl)
rqCallOut: script prefix for callout on each parsed request (default: none)
dispatch: script prefix for handling each request (default: ''Backend'')
server_id: server field to be sent with each HTTP response (default: ''Wub 3.0'')
server_port: server port to be reported to clients (may differ from actual port under proxying) (default: actual port)

max_conn: maximum simultaneous connections by any given client. (default: 10)
max: maximum number of workers. (default: 20)
incr: number of new workers to create on demand. (default: 5)
over: maximum number of connections to accept for each worker. (default: 10)
retry_wait: time to tell a client wait before retrying a request, under conditions of resource exhaustion (default: 20 seconds)

== Interface Provided ==

=== Got $request ===

Worker has parsed one request.  Decide how to process the request.
By default, invoke the -dispatch script on the request.

=== Connect $sock $ipaddr $rport args ===

Request from [Listener] to Handle a new incoming connection.  This results in the creation of a connection record, and its association with one of a pool of workers.  If this association fails due to overcommittment, an appropriate response is sent to the client connection (which is then dropped.)

=== Disconnect $id $error {$erroroptions} ===

Indication from [HttpdWorker] or [Backend] that connection has disconnected.

=== Idle {$script} ===

External request to stop accepting new connections, and go idle.
When idle, evaluate ''$script''

=== Live ===

External request to start accepting new connections after an Idle.

== Backend Interface ==

=== $dispatch Incoming $request ===

Request [Backend] to process incoming request.

=== $dispatch Disconnect $sock ==

Request [Backend] to disconnect connection currently on $sock.
