Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Moving some notes into new docs.txt.

  • Loading branch information...
commit 9adf25c27cf624b632e85e281949f8690d5b9976 1 parent 2ddba4e
Peter Seibel authored
Showing with 113 additions and 50 deletions.
  1. +107 −0 docs.txt
  2. +6 −50 notes.txt
107 docs.txt
View
@@ -0,0 +1,107 @@
+-*- mode: markup; -*-
+
+* Overview
+
+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 either returning a string or writing
+content to a stream. Handlers can also affect the response by setting
+HTTP response headers on the request object they are handed.
+
+* How to use
+
+** 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/>
56 notes.txt
View
@@ -1,49 +1,5 @@
-*- mode: markup; -*-
-* Parts
-
-** 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 lower-cased 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.
-
* What I did
** Gross stripping
@@ -84,7 +40,7 @@ Possibly combine request and reply objects into a single object.
* Threading
-create-request-handler-thread assumes that we will create
+create-request-handler-thread assumes that we will create
* Bugs?
@@ -112,12 +68,12 @@ Logging (where to and what format)
* Flow
-[acceptor] start ->
+[acceptor] start ->
[taskmaster] execute-acceptor ->
-[acceptor] accept-connections (in new thread) ->
-[taskmaster] handle-incoming-connection ->
-[acceptor] process-connection (in new thread for each connection)->
-[request] process-request (in loop) ->
+[acceptor] accept-connections (in new thread) ->
+[taskmaster] handle-incoming-connection ->
+[acceptor] process-connection (in new thread for each connection)->
+[request] process-request (in loop) ->
dispatch to user code.
* Response generation
Please sign in to comment.
Something went wrong with that request. Please try again.