The following functions implement the Emacs Web Server public API.
The following objects represent web servers and requests.
Every Emacs web server is an instance of the
Each instance includes the
handlers association list and
port passed to
ws-start, as well as the server network
process and a list of all active
ws-request class represents an active web request. The
process field holds the network process of the client and may
be used by handlers to respond to requests. The
holds an alist of information on the request for use by handlers. The
active fields are used to maintain header
parsing information across calls to the
The following functions start and stop Emacs web servers. The
ws-servers list holds all running servers.
ws-start starts a server listening on
handlers (see Handlers) to match and respond to requests.
An instance of the
ws-server class is returned.
ws-servers list holds all active Emacs web servers.
server deletes all related processes, and
frees the server’s port. Evaluate the following to stop all emacs web
(mapc #'ws-stop ws-servers)
ws-stop-all stops all emacs web servers by mapping
The following convenience functions automate many common tasks associated with responding to HTTP requests.
Send the headers required to start an HTTP response to
proc should be a
proc of an active
For example start a standard 200 “OK” HTML response with the following.
(ws-response-header process 200 '("Content-type" . "text/html"))
The encoding may optionally be set in the HTTP header. Send a UTF8 encoded response with the following.
(ws-response-header process 200 '("Content-type" . "text/plain; charset=utf-8"))
Additionally, when “Content-Encoding” or “Transfer-Encoding”
headers are supplied any subsequent data written to
ws-send will be encoded appropriately including sending the
appropriate data upon the end of transmission for chunked transfer
For example with the header
("Content-Encoding" . "gzip"), any
data subsequently written to
ws-send will be
compressed using the command specified in
Gzipped Transfer Encoding and Chunked Transfer Encoding
for more complete examples.
string to process
proc. If any Content or Transfer
encodings are in use, apply them to
string before sending.
ws-send-500 sends a default 500 “Internal Server Error”
ws-send-500 sends a default 404 “File Not Found” response to
ws-send-file sends the file located at
process. If the optional
mime-type is not set, then the
mime-type is determined by calling
path or is set to “application/octet-stream” if no mime-type
can be determined.
ws-send-directory-list sends the a listing of the files located
process. The list is sent as an HTML
list of links to the files. Optional argument
match may be set
to a regular expression, in which case only those files that match are
path is under the
(ws-in-directory-p "/tmp/" "pics") ⇒ "/tmp/pics" (ws-in-directory-p "/tmp/" "..") ⇒ nil (ws-in-directory-p "/tmp/" "~/pics") ⇒ nil
Return a version of
handler which is protected by
credentials. Handler should be a normal handler function
(see Handlers) and
credentials should be an association
list of usernames and passwords.
For example, a server running the following handlers,
(list (cons '(:GET . ".*") 'view-handler) (cons '(:POST . ".*") 'edit-handler))
could have authorization added by changing the handlers to the following.
(list (cons '(:GET . ".*") view-handler) (cons '(:POST . ".*") (ws-with-authentication 'org-ehtml-edit-handler '(("admin" . "password")))))
request is a web socket upgrade request (indicated by the
presence of the
:SEC-WEBSOCKET-KEY header argument) establish a
web socket connection to the client. Call
handler on web
socket messages received from the client.
(ws-web-socket-connect request (lambda (proc string) (process-send-string proc (ws-web-socket-frame (concat "you said: " string))))) ⇒ #<process ws-server <127.0.0.1:34921>>
The following variables may be changed to control the behavior of the
web server. Specifically the
ws-*-cmd variables specify the
command lines used to compress data according to content and or
transfer encoding HTTP headers passed to ws-response-header.
Command used for the “compress” Content or Transfer coding.
Command used for the “deflate” Content or Transfer coding.
Command used for the “gzip” Content or Transfer coding.