Merge commit '0cda39255827f283e7578cd469ae42daad9556a2' from js2-mode

[gnu-emacs-elpa] / packages / web-server / doc / web-server.texi

\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