--- /dev/null
+\input texinfo
+@c @setfilename emacs-web-server.info
+@documentencoding utf-8
+@settitle Emacs Web Server (web-server) User Manual
+
+@copying
+This file documents the Emacs Web Server (web-server)
+
+Copyright (C) 2013 Eric Schulte <schulte.eric@@gmail.com>
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3
+or any later version published by the Free Software Foundation;
+with the Invariant Section being ``GNU GENERAL PUBLIC LICENSE,''
+A copy of the license is included in the section entitled
+``GNU Free Documentation License.''
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Web Server: (web-server). Web Server for Emacs.
+@end direntry
+
+@titlepage
+@title Emacs Web Server (web-server) User Manual
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@c Output the table of the contents at the beginning.
+@contents
+
+@ifnottex
+@node Top, Introduction, (dir), (dir)
+@top Emacs Web Server User Manual
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Introduction:: Overview of the Emacs Web Server
+* Handlers:: Handlers respond to HTTP requests
+* Requests:: Getting information on HTTP requests
+* Usage Examples:: Examples demonstrating usage
+* Function Index:: List of Functions
+
+Appendices
+
+* Copying:: The GNU General Public License gives
+ you permission to redistribute GNU Emacs on
+ certain terms; it also explains that there is
+ no warranty.
+* GNU Free Documentation License:: The license for this documentation.
+* Index:: Complete index.
+
+
+
+
+@end menu
+
+@node Introduction, Handlers, Top, Top
+@chapter Introduction
+@cindex introduction
+
+The Emacs Web Server is a Web server implemented entirely in Emacs
+Lisp. HTTP requests are matched to handlers (@pxref{Handlers}) which
+are Emacs Lisp functions. Handlers receive as their only argument a
+request object (@pxref{Requests}) which holds information about the
+request and a process holding the HTTP network connection. Handlers
+write their responses directly to the network process.
+
+A number of examples (@pxref{Usage Examples}) demonstrate usage of the
+Emacs Web Server. All public functions of the Emacs Web Server are
+listed (@pxref{Function Index}).
+
+@node Handlers, Requests, Handlers, Top
+@chapter Handlers
+@cindex handlers
+
+The function @code{ws-start} takes takes two arguments @code{handlers}
+and @code{port}. It starts a server listening on @code{port}
+responding to requests with @code{handlers}. @code{Handlers} may be
+either a single function or an association list composed of pairs of
+matchers and handler functions. When @code{handlers} is a single
+function the given function is used to serve every request, when it is
+an association list, the function of the first matcher to match each
+request handles that request.
+
+@section Matchers
+@cindex matchers
+
+Matchers may be a regular expression or a function. Regular
+expression matchers consists of an HTTP header and a regular
+expression. When the regular expression matches the content of the
+given header the matcher succeeds and the associated handler is
+called. For example the following matches any @code{GET} request
+whose path starts with the substring ``foo''.
+
+@example
+(:GET . "^foo")
+@end example
+
+A function matcher is a function which takes the request object
+(@pxref{Requests}) and succeeds when the function returns a non-nil
+value. For example the following matcher matches every request,
+
+@example
+(lambda (_) t)
+@end example
+
+and the following matches only requests in which the supplied
+``number'' parameter is odd.
+
+@example
+(lambda (request)
+ (oddp (string-to-number (cdr (assoc "number" request)))))
+@end example
+
+@section Handler Function
+@cindex handler function
+
+Each handler is a function which takes a request object
+(@pxref{Requests}) as its only argument. The function may respond to
+the request by writing to the network process held in the
+@code{process} field of the request object. For example, the
+@code{process-send-string} function may be used to write string data
+to a request as in the following.
+
+@example
+ (process-send-string (process request) "hello world")
+@end example
+
+When the handler function exits the connection is terminated unless
+the handler function returns the keyword @code{:keep-alive}.
+
+@node Requests, Usage Examples, Handlers, Top
+@chapter Requests
+@cindex requests
+
+Each HTTP requests is represented using a @code{ws-request} object
+(@pxref{ws-request}). The request object serves two purposes, one
+internal and one external. Internally, request objects are used to
+hold state while HTTP headers are parsed incrementally as the HTTP
+request text is received from the network. Externally, request
+objects are used to decide which handler to call, and are then passed
+as the only argument to the called handler.
+
+In addition to fields used internally, each @code{ws-request} object
+holds the network process in the @code{process} and holds all HTTP
+headers and request GET or POST parameters in the @code{headers}
+alist. HTML Headers are keyed using uppercase keywords (e.g.,
+@code{:GET}), and user supplied parameters are keyed using the string
+name of the parameter.
+
+The @code{process} field may be used by handlers to send data to a
+client as in the following example.
+
+@example
+(process-send-string (process request) "hello world")
+@end example
+
+The @code{headers} field may be used to access request information
+such as the requested path,
+
+@example
+(cdr (assoc :GET (headers request)))
+@end example
+
+or named parameters as from a web form.
+
+@example
+(cdr (assoc "message" (headers request)))
+@end example
+
+@node Usage Examples, Hello World, Requests, Top
+@chapter Usage Examples
+@cindex usage examples
+
+These examples demonstrate usage.
+@menu
+* Hello World:: Serve ``Hello World'' to every request
+* Hello World UTF8:: Serve ``Hello World'' w/UTF8 encoding
+* Hello World HTML:: Serve ``Hello World'' in HTML
+* File Server:: Serve files from a document root
+* URL Parameter Echo:: Echo parameters from a URL query string
+* POST Echo:: Echo POST parameters back
+* Basic Authentication:: BASIC HTTP authentication
+* Org-mode Export:: Export files to HTML and Tex
+* File Upload:: Upload files and return their sha1sum
+* Web Socket:: Web socket echo server
+* Gzipped Transfer Encoding:: Gzip content encoding
+* Chunked Transfer Encoding:: Chunked transfer encoding
+@end menu
+
+@node Hello World, Hello World UTF8, Usage Examples, Usage Examples
+@section Hello World
+
+The simplest possible ``hello world'' example. The handler consists
+of a single (matcher . handler) pair. The function matcher matches
+@emph{every} incoming HTTP request. The handler responds by setting
+the content type to @code{text/plain}, and then sending the string
+``hello world''. When the handler exits the network connection of the
+request is closed.
+
+@verbatiminclude ../examples/000-hello-world.el
+
+@node Hello World UTF8, Hello World HTML, Hello World, Usage Examples
+@section Hello World UTF8
+
+This example only differs from the previous in that the
+``Content-type'' indicates UTF8 encoded data, and the hello world sent
+is selected at random from a list of different languages.
+
+@verbatiminclude ../examples/001-hello-world-utf8.el
+
+@node Hello World HTML, File Server, Hello World UTF8, Usage Examples
+@section Hello World HTML
+@verbatiminclude ../examples/002-hello-world-html.el
+
+This variation of the ``hello world'' example sends a @code{text/html}
+response instead of a simple @code{text/plain} response.
+
+@node File Server, URL Parameter Echo, Hello World HTML, Usage Examples
+@section File Server
+
+The following example implements a file server which will serve files
+from the @code{docroot} document root set to the current working
+directory in this example. Four helper functions are used;
+@code{ws-in-directory-p} is used to check if the requested path is
+within the document root. If not then @code{ws-send-404} is used to
+send a default ``File Not Found''. If so then the file is served with
+@code{ws-send-file} (which appropriately sets the mime-type of the
+response based on the extension of the file) if it is a file or is
+served with @code{ws-send-directory-list} if it is a directory.
+
+@verbatiminclude ../examples/003-file-server.el
+
+@node URL Parameter Echo, POST Echo, File Server, Usage Examples
+@section URL Parameter Echo
+
+This example demonstrates access of URL-encoded parameters in a
+@code{GET} request. For example the following URL
+@url{http://localhost:9005/example?foo=bar&baz=qux} will render as
+the following HTML table.
+
+@multitable @columnfractions .5 .5
+@item foo @tab bar
+@item baz @tab qux
+@end multitable
+
+@verbatiminclude ../examples/004-url-param-echo.el
+
+@node POST Echo, Basic Authentication, URL Parameter Echo, Usage Examples
+@section POST Echo
+
+The following example echos back the content of the ``message'' field
+in a @code{POST} request.
+
+@verbatiminclude ../examples/005-post-echo.el
+
+@node Basic Authentication, Org-mode Export, POST Echo, Usage Examples
+@section Basic Authentication
+
+The following example demonstrates BASIC HTTP authentication. The
+handler prompts an unauthenticated client for authentication by
+sending a ``WWW-Authenticate'' header.
+
+@example
+(ws-response-header process 401
+ '("WWW-Authenticate" . "Basic realm=\"example\"")
+ '("Content-type" . "text/plain"))
+@end example
+
+The client replies by setting the ``Authorization'' HTTP header which
+is parsed into a list of the form @code{(PROTOCOL USERNAME
+. PASSWORD)}. Currently only BASIC HTTP authentication is supported.
+
+@noindent
+Note: BASIC HTTP authentication passes user credentials in plain text
+between the client and the server and should generally only be used
+with HTTPS network encryption. While the Emacs web server currently
+doesn't support HTTPS network encryption it may be run behind an HTTPS
+proxy server (e.g., Apache or Nginx) with HTTPS support.
+
+@verbatiminclude ../examples/006-basic-authentication.el
+
+@node Org-mode Export, File Upload, Basic Authentication, Usage Examples
+@section Org-mode Export
+
+The following example exports a directory of Org-mode files as either
+text, HTML or LaTeX. The Org-mode export engine is used to export
+files on-demand as they are requested.
+
+@verbatiminclude ../examples/007-org-mode-file-server.el
+
+@node File Upload, Web Socket, Org-mode Export, Usage Examples
+@section File Upload
+
+The following example demonstrates accessing an uploaded file. This
+simple server accesses the file named ``file'' and returns it's
+sha1sum and file name.
+
+@verbatiminclude ../examples/008-file-upload.el
+
+A file may be uploaded from an HTML form, or using the @code{curl}
+program as in the following example.
+
+@example
+$ curl -s -F file=@/usr/share/emacs/24.3/etc/COPYING localhost:9008
+8624bcdae55baeef00cd11d5dfcfa60f68710a02 COPYING
+$ sha1sum /usr/share/emacs/24.3/etc/COPYING
+8624bcdae55baeef00cd11d5dfcfa60f68710a02 /usr/share/emacs/24.3/etc/COPYING
+@end example
+
+@node Web Socket, Chunked Transfer Encoding, File Upload, Usage Examples
+@section Web Socket
+
+Example demonstrating the use of web sockets for full duplex
+communication between clients and the server. Handlers may use the
+@code{ws-web-socket-connect} function (@pxref{ws-web-socket-connect})
+to check for and respond to a web socket upgrade request sent by the
+client (as demonstrated with the @code{new WebSocket} JavaScript code
+in the example). Upon successfully initializing a web socket
+connection the call to @code{ws-web-socket-connect} will return the
+web socket network process. This process may then be used by the
+server to communicate with the client over the web socket using the
+@code{process-send-string} and @code{ws-web-socket-frame} functions.
+All web socket communication must be wrapped in frames using the
+@code{ws-web-socket-frame} function.
+
+The handler must pass a function as the second argument to
+@code{ws-web-socket-connect}. This function will be called on every
+web socket message received from the client.
+
+@noindent
+Note: in order to keep the web socket connection alive the request
+handler from which @code{ws-web-socket-connect} is called must return
+the @code{:keep-alive} keyword, as demonstrated in the example.
+
+@verbatiminclude ../examples/009-web-socket.el
+
+@node Gzipped Transfer Encoding, Chunked Transfer Encoding, Web Socket, Usage Examples
+@section Gzipped Transfer Encoding
+
+HTTP Responses may be compressed by setting the ``gzip'' (or
+``compress'' or ``deflate'') content- or transfer-encoding HTTP
+headers in @code{ws-response-header}. Any further data sent to the
+process using @code{ws-send} will automatically be appropriately
+compressed.
+
+@verbatiminclude ../examples/016-content-encoding-gzip.el
+
+@node Chunked Transfer Encoding, Function Index, Web Socket, Usage Examples
+@section Chunked Transfer Encoding
+
+Similarly, HTTP Responses may be sent using the ``chunked'' transfer
+encoding by passing the appropriate HTTP header to
+@code{ws-response-header}. Any further data sent to the process using
+@code{ws-send} will automatically be appropriately encoded for chunked
+transfer.
+
+@verbatiminclude ../examples/017-transfer-encoding-chunked.el
+
+@node Function Index, Copying, Usage Examples, Top
+@chapter Function Index
+@cindex function index
+
+The following functions implement the Emacs Web Server public API.
+
+@section Objects
+The following objects represent web servers and requests.
+
+@anchor{ws-server}
+@deftp Class ws-server handlers process port requests
+Every Emacs web server is an instance of the @code{ws-server} class.
+Each instance includes the @code{handlers} association list and
+@code{port} passed to @code{ws-start}, as well as the server network
+@code{process} and a list of all active @code{requests}.
+@end deftp
+
+@anchor{ws-request}
+@deftp Class ws-request process pending context boundary index active headers
+The @code{ws-request} class represents an active web request. The
+@code{process} field holds the network process of the client and may
+be used by handlers to respond to requests. The @code{headers} field
+holds an alist of information on the request for use by handlers. The
+remaining @code{pending}, @code{context}, @code{boundary},
+@code{index} and @code{active} fields are used to maintain header
+parsing information across calls to the @code{ws-filter} function.
+@end deftp
+
+@section Starting and Stopping Servers
+@cindex start and stop
+The following functions start and stop Emacs web servers. The
+@code{ws-servers} list holds all running servers.
+
+@anchor{ws-start}
+@defun ws-start handlers port &optional log-buffer &rest network-args
+@code{ws-start} starts a server listening on @code{port} using
+@code{handlers} (@pxref{Handlers}) to match and respond to requests.
+An instance of the @code{ws-server} class is returned.
+@end defun
+
+@anchor{ws-servers}
+@defvar ws-servers
+The @code{ws-servers} list holds all active Emacs web servers.
+@end defvar
+
+@anchor{ws-stop}
+@defun ws-stop server
+@code{ws-stop} stops @code{server} deletes all related processes, and
+frees the server's port. Evaluate the following to stop all emacs web
+servers.
+@example
+(mapc #'ws-stop ws-servers)
+@end example
+@end defun
+
+@anchor{ws-stop-all}
+@defun ws-stop-all
+@code{ws-stop-all} stops all emacs web servers by mapping
+@code{ws-stop} over @code{ws-servers}.
+@end defun
+
+@section Convenience Functions
+The following convenience functions automate many common tasks
+associated with responding to HTTP requests.
+
+@anchor{ws-response-header}
+@cindex content type
+@defun ws-response-header process code &rest headers
+Send the headers required to start an HTTP response to @code{proc}.
+@code{proc} should be a @code{ws-request} @code{proc} of an active
+request.
+
+For example start a standard 200 ``OK'' HTML response with the
+following.
+
+@example
+(ws-response-header process 200 '("Content-type" . "text/html"))
+@end example
+
+The encoding may optionally be set in the HTTP header. Send a UTF8
+encoded response with the following.
+
+@example
+(ws-response-header process 200
+ '("Content-type" . "text/plain; charset=utf-8"))
+@end example
+
+Additionally, when ``Content-Encoding'' or ``Transfer-Encoding''
+headers are supplied any subsequent data written to @code{proc} using
+@code{ws-send} will be encoded appropriately including sending the
+appropriate data upon the end of transmission for chunked transfer
+encoding.
+
+For example with the header @code{("Content-Encoding" . "gzip")}, any
+data subsequently written to @code{proc} using @code{ws-send} will be
+compressed using the command specified in @code{ws-gzip-cmd}. See
+@ref{Gzipped Transfer Encoding} and @ref{Chunked Transfer Encoding}
+for more complete examples.
+
+@end defun
+
+@anchor{ws-send}
+@defun ws-send proc string
+Send @code{string} to process @code{proc}. If any Content or Transfer
+encodings are in use, apply them to @code{string} before sending.
+@end defun
+
+@anchor{ws-send-500}
+@defun ws-send-500 process &rest msg-and-args
+@code{ws-send-500} sends a default 500 ``Internal Server Error''
+response to @code{process}.
+@end defun
+
+@anchor{ws-send-404}
+@defun ws-send-404 process &rest msg-and-args
+@code{ws-send-500} sends a default 404 ``File Not Found'' response to
+@code{process}.
+@end defun
+
+@anchor{ws-send-file}
+@defun ws-send-file process path &optional mime-type
+@code{ws-send-file} sends the file located at @code{path} to
+@code{process}. If the optional @code{mime-type} is not set, then the
+mime-type is determined by calling @code{mm-default-file-encoding} on
+@code{path} or is set to ``application/octet-stream'' if no mime-type
+can be determined.
+@end defun
+
+@anchor{ws-send-directory-list}
+@defun ws-send-directory-list process directory &optional match
+@code{ws-send-directory-list} sends the a listing of the files located
+in @code{directory} to @code{process}. The list is sent as an HTML
+list of links to the files. Optional argument @code{match} may be set
+to a regular expression, in which case only those files that match are
+listed.
+@end defun
+
+@anchor{ws-in-directory-p}
+@defun ws-in-directory-p parent path
+Check if @code{path} is under the @code{parent} directory.
+
+@example
+(ws-in-directory-p "/tmp/" "pics")
+ @result{} "/tmp/pics"
+
+(ws-in-directory-p "/tmp/" "..")
+ @result{} nil
+
+(ws-in-directory-p "/tmp/" "~/pics")
+ @result{} nil
+@end example
+@end defun
+
+@anchor{ws-with-authentication}
+@defun ws-with-authentication handler credentials &optional realm unauth invalid
+Return a version of @code{handler} which is protected by
+@code{credentials}. Handler should be a normal handler function
+(@pxref{Handlers}) and @code{credentials} should be an association
+list of usernames and passwords.
+
+For example, a server running the following handlers,
+
+@example
+(list (cons '(:GET . ".*") 'view-handler)
+ (cons '(:POST . ".*") 'edit-handler))
+@end example
+
+could have authorization added by changing the handlers to the
+following.
+
+@example
+(list (cons '(:GET . ".*") view-handler)
+ (cons '(:POST . ".*") (ws-with-authentication
+ 'org-ehtml-edit-handler
+ '(("admin" . "password")))))
+@end example
+
+@end defun
+
+@anchor{ws-web-socket-connect}
+@defun ws-web-socket-connect request handler
+If @code{request} is a web socket upgrade request (indicated by the
+presence of the @code{:SEC-WEBSOCKET-KEY} header argument) establish a
+web socket connection to the client. Call @code{handler} on web
+socket messages received from the client.
+
+@example
+(ws-web-socket-connect request
+ (lambda (proc string)
+ (process-send-string proc
+ (ws-web-socket-frame (concat "you said: " string)))))
+ @result{} #<process ws-server <127.0.0.1:34921>>
+@end example
+@end defun
+
+@section Customization Variables
+The following variables may be changed to control the behavior of the
+web server. Specifically the @code{ws-*-cmd} variables specify the
+command lines used to compress data according to content and or
+transfer encoding HTTP headers passed to @ref{ws-response-header}.
+
+@anchor{ws-compress-cmd}
+@defvar ws-compress-cmd
+Command used for the ``compress'' Content or Transfer coding.
+@end defvar
+
+@anchor{ws-deflate-cmd}
+@defvar ws-deflate-cmd
+Command used for the ``deflate'' Content or Transfer coding.
+@end defvar
+
+@anchor{ws-gzip-cmd}
+@defvar ws-gzip-cmd
+Command used for the ``gzip'' Content or Transfer coding.
+@end defvar
+
+@node Copying, GNU Free Documentation License, Function Index, Top
+@appendix GNU GENERAL PUBLIC LICENSE
+@include gpl.texi
+
+@node GNU Free Documentation License, Index, Copying, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index, , GNU Free Documentation License, Top
+@unnumbered Index
+
+@c Combine all index (function variable type and concept) types into a
+@c single index.
+@syncodeindex fn cp
+@syncodeindex vr cp
+@syncodeindex tp cp
+@printindex cp
+
+@bye