2 @c @setfilename emacs-web-server.info
3 @documentencoding utf-8
4 @settitle Emacs Web Server (web-server) User Manual
7 This file documents the Emacs Web Server (web-server)
9 Copyright (C) 2013 Eric Schulte <schulte.eric@@gmail.com>
12 Permission is granted to copy, distribute and/or modify this document
13 under the terms of the GNU Free Documentation License, Version 1.3
14 or any later version published by the Free Software Foundation;
15 with the Invariant Section being ``GNU GENERAL PUBLIC LICENSE,''
16 A copy of the license is included in the section entitled
17 ``GNU Free Documentation License.''
23 * Web Server: (web-server). Web Server for Emacs.
27 @title Emacs Web Server (web-server) User Manual
29 @vskip 0pt plus 1filll
33 @c Output the table of the contents at the beginning.
37 @node Top, Introduction, (dir), (dir)
38 @top Emacs Web Server User Manual
44 * Introduction:: Overview of the Emacs Web Server
45 * Handlers:: Handlers respond to HTTP requests
46 * Requests:: Getting information on HTTP requests
47 * Usage Examples:: Examples demonstrating usage
48 * Function Index:: List of Functions
52 * Copying:: The GNU General Public License gives
53 you permission to redistribute GNU Emacs on
54 certain terms; it also explains that there is
56 * GNU Free Documentation License:: The license for this documentation.
57 * Index:: Complete index.
64 @node Introduction, Handlers, Top, Top
68 The Emacs Web Server is a Web server implemented entirely in Emacs
69 Lisp. HTTP requests are matched to handlers (@pxref{Handlers}) which
70 are Emacs Lisp functions. Handlers receive as their only argument a
71 request object (@pxref{Requests}) which holds information about the
72 request and a process holding the HTTP network connection. Handlers
73 write their responses directly to the network process.
75 A number of examples (@pxref{Usage Examples}) demonstrate usage of the
76 Emacs Web Server. All public functions of the Emacs Web Server are
77 listed (@pxref{Function Index}).
79 @node Handlers, Requests, Handlers, Top
83 The function @code{ws-start} takes takes two arguments @code{handlers}
84 and @code{port}. It starts a server listening on @code{port}
85 responding to requests with @code{handlers}. @code{Handlers} may be
86 either a single function or an association list composed of pairs of
87 matchers and handler functions. When @code{handlers} is a single
88 function the given function is used to serve every request, when it is
89 an association list, the function of the first matcher to match each
90 request handles that request.
95 Matchers may be a regular expression or a function. Regular
96 expression matchers consists of an HTTP header and a regular
97 expression. When the regular expression matches the content of the
98 given header the matcher succeeds and the associated handler is
99 called. For example the following matches any @code{GET} request
100 whose path starts with the substring ``foo''.
106 A function matcher is a function which takes the request object
107 (@pxref{Requests}) and succeeds when the function returns a non-nil
108 value. For example the following matcher matches every request,
114 and the following matches only requests in which the supplied
115 ``number'' parameter is odd.
119 (oddp (string-to-number (cdr (assoc "number" request)))))
122 @section Handler Function
123 @cindex handler function
125 Each handler is a function which takes a request object
126 (@pxref{Requests}) as its only argument. The function may respond to
127 the request by writing to the network process held in the
128 @code{process} field of the request object. For example, the
129 @code{process-send-string} function may be used to write string data
130 to a request as in the following.
133 (process-send-string (process request) "hello world")
136 When the handler function exits the connection is terminated unless
137 the handler function returns the keyword @code{:keep-alive}.
139 @node Requests, Usage Examples, Handlers, Top
143 Each HTTP requests is represented using a @code{ws-request} object
144 (@pxref{ws-request}). The request object serves two purposes, one
145 internal and one external. Internally, request objects are used to
146 hold state while HTTP headers are parsed incrementally as the HTTP
147 request text is received from the network. Externally, request
148 objects are used to decide which handler to call, and are then passed
149 as the only argument to the called handler.
151 In addition to fields used internally, each @code{ws-request} object
152 holds the network process in the @code{process} and holds all HTTP
153 headers and request GET or POST parameters in the @code{headers}
154 alist. HTML Headers are keyed using uppercase keywords (e.g.,
155 @code{:GET}), and user supplied parameters are keyed using the string
156 name of the parameter.
158 The @code{process} field may be used by handlers to send data to a
159 client as in the following example.
162 (process-send-string (process request) "hello world")
165 The @code{headers} field may be used to access request information
166 such as the requested path,
169 (cdr (assoc :GET (headers request)))
172 or named parameters as from a web form.
175 (cdr (assoc "message" (headers request)))
178 @node Usage Examples, Hello World, Requests, Top
179 @chapter Usage Examples
180 @cindex usage examples
182 These examples demonstrate usage.
184 * Hello World:: Serve ``Hello World'' to every request
185 * Hello World UTF8:: Serve ``Hello World'' w/UTF8 encoding
186 * Hello World HTML:: Serve ``Hello World'' in HTML
187 * File Server:: Serve files from a document root
188 * URL Parameter Echo:: Echo parameters from a URL query string
189 * POST Echo:: Echo POST parameters back
190 * Basic Authentication:: BASIC HTTP authentication
191 * Org-mode Export:: Export files to HTML and Tex
192 * File Upload:: Upload files and return their sha1sum
193 * Web Socket:: Web socket echo server
194 * Gzipped Transfer Encoding:: Gzip content encoding
195 * Chunked Transfer Encoding:: Chunked transfer encoding
198 @node Hello World, Hello World UTF8, Usage Examples, Usage Examples
201 The simplest possible ``hello world'' example. The handler consists
202 of a single (matcher . handler) pair. The function matcher matches
203 @emph{every} incoming HTTP request. The handler responds by setting
204 the content type to @code{text/plain}, and then sending the string
205 ``hello world''. When the handler exits the network connection of the
208 @verbatiminclude ../examples/000-hello-world.el
210 @node Hello World UTF8, Hello World HTML, Hello World, Usage Examples
211 @section Hello World UTF8
213 This example only differs from the previous in that the
214 ``Content-type'' indicates UTF8 encoded data, and the hello world sent
215 is selected at random from a list of different languages.
217 @verbatiminclude ../examples/001-hello-world-utf8.el
219 @node Hello World HTML, File Server, Hello World UTF8, Usage Examples
220 @section Hello World HTML
221 @verbatiminclude ../examples/002-hello-world-html.el
223 This variation of the ``hello world'' example sends a @code{text/html}
224 response instead of a simple @code{text/plain} response.
226 @node File Server, URL Parameter Echo, Hello World HTML, Usage Examples
229 The following example implements a file server which will serve files
230 from the @code{docroot} document root set to the current working
231 directory in this example. Four helper functions are used;
232 @code{ws-in-directory-p} is used to check if the requested path is
233 within the document root. If not then @code{ws-send-404} is used to
234 send a default ``File Not Found''. If so then the file is served with
235 @code{ws-send-file} (which appropriately sets the mime-type of the
236 response based on the extension of the file) if it is a file or is
237 served with @code{ws-send-directory-list} if it is a directory.
239 @verbatiminclude ../examples/003-file-server.el
241 @node URL Parameter Echo, POST Echo, File Server, Usage Examples
242 @section URL Parameter Echo
244 This example demonstrates access of URL-encoded parameters in a
245 @code{GET} request. For example the following URL
246 @url{http://localhost:9005/example?foo=bar&baz=qux} will render as
247 the following HTML table.
249 @multitable @columnfractions .5 .5
254 @verbatiminclude ../examples/004-url-param-echo.el
256 @node POST Echo, Basic Authentication, URL Parameter Echo, Usage Examples
259 The following example echos back the content of the ``message'' field
260 in a @code{POST} request.
262 @verbatiminclude ../examples/005-post-echo.el
264 @node Basic Authentication, Org-mode Export, POST Echo, Usage Examples
265 @section Basic Authentication
267 The following example demonstrates BASIC HTTP authentication. The
268 handler prompts an unauthenticated client for authentication by
269 sending a ``WWW-Authenticate'' header.
272 (ws-response-header process 401
273 '("WWW-Authenticate" . "Basic realm=\"example\"")
274 '("Content-type" . "text/plain"))
277 The client replies by setting the ``Authorization'' HTTP header which
278 is parsed into a list of the form @code{(PROTOCOL USERNAME
279 . PASSWORD)}. Currently only BASIC HTTP authentication is supported.
282 Note: BASIC HTTP authentication passes user credentials in plain text
283 between the client and the server and should generally only be used
284 with HTTPS network encryption. While the Emacs web server currently
285 doesn't support HTTPS network encryption it may be run behind an HTTPS
286 proxy server (e.g., Apache or Nginx) with HTTPS support.
288 @verbatiminclude ../examples/006-basic-authentication.el
290 @node Org-mode Export, File Upload, Basic Authentication, Usage Examples
291 @section Org-mode Export
293 The following example exports a directory of Org-mode files as either
294 text, HTML or LaTeX. The Org-mode export engine is used to export
295 files on-demand as they are requested.
297 @verbatiminclude ../examples/007-org-mode-file-server.el
299 @node File Upload, Web Socket, Org-mode Export, Usage Examples
302 The following example demonstrates accessing an uploaded file. This
303 simple server accesses the file named ``file'' and returns it's
304 sha1sum and file name.
306 @verbatiminclude ../examples/008-file-upload.el
308 A file may be uploaded from an HTML form, or using the @code{curl}
309 program as in the following example.
312 $ curl -s -F file=@/usr/share/emacs/24.3/etc/COPYING localhost:9008
313 8624bcdae55baeef00cd11d5dfcfa60f68710a02 COPYING
314 $ sha1sum /usr/share/emacs/24.3/etc/COPYING
315 8624bcdae55baeef00cd11d5dfcfa60f68710a02 /usr/share/emacs/24.3/etc/COPYING
318 @node Web Socket, Chunked Transfer Encoding, File Upload, Usage Examples
321 Example demonstrating the use of web sockets for full duplex
322 communication between clients and the server. Handlers may use the
323 @code{ws-web-socket-connect} function (@pxref{ws-web-socket-connect})
324 to check for and respond to a web socket upgrade request sent by the
325 client (as demonstrated with the @code{new WebSocket} JavaScript code
326 in the example). Upon successfully initializing a web socket
327 connection the call to @code{ws-web-socket-connect} will return the
328 web socket network process. This process may then be used by the
329 server to communicate with the client over the web socket using the
330 @code{process-send-string} and @code{ws-web-socket-frame} functions.
331 All web socket communication must be wrapped in frames using the
332 @code{ws-web-socket-frame} function.
334 The handler must pass a function as the second argument to
335 @code{ws-web-socket-connect}. This function will be called on every
336 web socket message received from the client.
339 Note: in order to keep the web socket connection alive the request
340 handler from which @code{ws-web-socket-connect} is called must return
341 the @code{:keep-alive} keyword, as demonstrated in the example.
343 @verbatiminclude ../examples/009-web-socket.el
345 @node Gzipped Transfer Encoding, Chunked Transfer Encoding, Web Socket, Usage Examples
346 @section Gzipped Transfer Encoding
348 HTTP Responses may be compressed by setting the ``gzip'' (or
349 ``compress'' or ``deflate'') content- or transfer-encoding HTTP
350 headers in @code{ws-response-header}. Any further data sent to the
351 process using @code{ws-send} will automatically be appropriately
354 @verbatiminclude ../examples/016-content-encoding-gzip.el
356 @node Chunked Transfer Encoding, Function Index, Web Socket, Usage Examples
357 @section Chunked Transfer Encoding
359 Similarly, HTTP Responses may be sent using the ``chunked'' transfer
360 encoding by passing the appropriate HTTP header to
361 @code{ws-response-header}. Any further data sent to the process using
362 @code{ws-send} will automatically be appropriately encoded for chunked
365 @verbatiminclude ../examples/017-transfer-encoding-chunked.el
367 @node Function Index, Copying, Usage Examples, Top
368 @chapter Function Index
369 @cindex function index
371 The following functions implement the Emacs Web Server public API.
374 The following objects represent web servers and requests.
377 @deftp Class ws-server handlers process port requests
378 Every Emacs web server is an instance of the @code{ws-server} class.
379 Each instance includes the @code{handlers} association list and
380 @code{port} passed to @code{ws-start}, as well as the server network
381 @code{process} and a list of all active @code{requests}.
385 @deftp Class ws-request process pending context boundary index active headers
386 The @code{ws-request} class represents an active web request. The
387 @code{process} field holds the network process of the client and may
388 be used by handlers to respond to requests. The @code{headers} field
389 holds an alist of information on the request for use by handlers. The
390 remaining @code{pending}, @code{context}, @code{boundary},
391 @code{index} and @code{active} fields are used to maintain header
392 parsing information across calls to the @code{ws-filter} function.
395 @section Starting and Stopping Servers
396 @cindex start and stop
397 The following functions start and stop Emacs web servers. The
398 @code{ws-servers} list holds all running servers.
401 @defun ws-start handlers port &optional log-buffer &rest network-args
402 @code{ws-start} starts a server listening on @code{port} using
403 @code{handlers} (@pxref{Handlers}) to match and respond to requests.
404 An instance of the @code{ws-server} class is returned.
409 The @code{ws-servers} list holds all active Emacs web servers.
413 @defun ws-stop server
414 @code{ws-stop} stops @code{server} deletes all related processes, and
415 frees the server's port. Evaluate the following to stop all emacs web
418 (mapc #'ws-stop ws-servers)
424 @code{ws-stop-all} stops all emacs web servers by mapping
425 @code{ws-stop} over @code{ws-servers}.
428 @section Convenience Functions
429 The following convenience functions automate many common tasks
430 associated with responding to HTTP requests.
432 @anchor{ws-response-header}
434 @defun ws-response-header process code &rest headers
435 Send the headers required to start an HTTP response to @code{proc}.
436 @code{proc} should be a @code{ws-request} @code{proc} of an active
439 For example start a standard 200 ``OK'' HTML response with the
443 (ws-response-header process 200 '("Content-type" . "text/html"))
446 The encoding may optionally be set in the HTTP header. Send a UTF8
447 encoded response with the following.
450 (ws-response-header process 200
451 '("Content-type" . "text/plain; charset=utf-8"))
454 Additionally, when ``Content-Encoding'' or ``Transfer-Encoding''
455 headers are supplied any subsequent data written to @code{proc} using
456 @code{ws-send} will be encoded appropriately including sending the
457 appropriate data upon the end of transmission for chunked transfer
460 For example with the header @code{("Content-Encoding" . "gzip")}, any
461 data subsequently written to @code{proc} using @code{ws-send} will be
462 compressed using the command specified in @code{ws-gzip-cmd}. See
463 @ref{Gzipped Transfer Encoding} and @ref{Chunked Transfer Encoding}
464 for more complete examples.
469 @defun ws-send proc string
470 Send @code{string} to process @code{proc}. If any Content or Transfer
471 encodings are in use, apply them to @code{string} before sending.
475 @defun ws-send-500 process &rest msg-and-args
476 @code{ws-send-500} sends a default 500 ``Internal Server Error''
477 response to @code{process}.
481 @defun ws-send-404 process &rest msg-and-args
482 @code{ws-send-500} sends a default 404 ``File Not Found'' response to
486 @anchor{ws-send-file}
487 @defun ws-send-file process path &optional mime-type
488 @code{ws-send-file} sends the file located at @code{path} to
489 @code{process}. If the optional @code{mime-type} is not set, then the
490 mime-type is determined by calling @code{mm-default-file-encoding} on
491 @code{path} or is set to ``application/octet-stream'' if no mime-type
495 @anchor{ws-send-directory-list}
496 @defun ws-send-directory-list process directory &optional match
497 @code{ws-send-directory-list} sends the a listing of the files located
498 in @code{directory} to @code{process}. The list is sent as an HTML
499 list of links to the files. Optional argument @code{match} may be set
500 to a regular expression, in which case only those files that match are
504 @anchor{ws-in-directory-p}
505 @defun ws-in-directory-p parent path
506 Check if @code{path} is under the @code{parent} directory.
509 (ws-in-directory-p "/tmp/" "pics")
510 @result{} "/tmp/pics"
512 (ws-in-directory-p "/tmp/" "..")
515 (ws-in-directory-p "/tmp/" "~/pics")
520 @anchor{ws-with-authentication}
521 @defun ws-with-authentication handler credentials &optional realm unauth invalid
522 Return a version of @code{handler} which is protected by
523 @code{credentials}. Handler should be a normal handler function
524 (@pxref{Handlers}) and @code{credentials} should be an association
525 list of usernames and passwords.
527 For example, a server running the following handlers,
530 (list (cons '(:GET . ".*") 'view-handler)
531 (cons '(:POST . ".*") 'edit-handler))
534 could have authorization added by changing the handlers to the
538 (list (cons '(:GET . ".*") view-handler)
539 (cons '(:POST . ".*") (ws-with-authentication
540 'org-ehtml-edit-handler
541 '(("admin" . "password")))))
546 @anchor{ws-web-socket-connect}
547 @defun ws-web-socket-connect request handler
548 If @code{request} is a web socket upgrade request (indicated by the
549 presence of the @code{:SEC-WEBSOCKET-KEY} header argument) establish a
550 web socket connection to the client. Call @code{handler} on web
551 socket messages received from the client.
554 (ws-web-socket-connect request
555 (lambda (proc string)
556 (process-send-string proc
557 (ws-web-socket-frame (concat "you said: " string)))))
558 @result{} #<process ws-server <127.0.0.1:34921>>
562 @section Customization Variables
563 The following variables may be changed to control the behavior of the
564 web server. Specifically the @code{ws-*-cmd} variables specify the
565 command lines used to compress data according to content and or
566 transfer encoding HTTP headers passed to @ref{ws-response-header}.
568 @anchor{ws-compress-cmd}
569 @defvar ws-compress-cmd
570 Command used for the ``compress'' Content or Transfer coding.
573 @anchor{ws-deflate-cmd}
574 @defvar ws-deflate-cmd
575 Command used for the ``deflate'' Content or Transfer coding.
580 Command used for the ``gzip'' Content or Transfer coding.
583 @node Copying, GNU Free Documentation License, Function Index, Top
584 @appendix GNU GENERAL PUBLIC LICENSE
587 @node GNU Free Documentation License, Index, Copying, Top
588 @appendix GNU Free Documentation License
589 @include doclicense.texi
591 @node Index, , GNU Free Documentation License, Top
594 @c Combine all index (function variable type and concept) types into a