5 Function Index

The following functions implement the Emacs Web Server public API.

5.1 Objects

The following objects represent web servers and requests.

Class: ws-server handlers process port requests

Every Emacs web server is an instance of the ws-server class. 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 requests.

Class: ws-request process pending context boundary index active headers

The 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 headers field holds an alist of information on the request for use by handlers. The remaining pending, context, boundary, index and active fields are used to maintain header parsing information across calls to the ws-filter function.

5.2 Starting and Stopping Servers

The following functions start and stop Emacs web servers. The ws-servers list holds all running servers.

Function: ws-start handlers port &optional log-buffer &rest network-args

ws-start starts a server listening on port using handlers (see Handlers) to match and respond to requests. An instance of the ws-server class is returned.

Variable: ws-servers

The ws-servers list holds all active Emacs web servers.

Function: ws-stop server

ws-stop stops server deletes all related processes, and frees the server’s port. Evaluate the following to stop all emacs web servers.

(mapc #'ws-stop ws-servers)

Function: ws-stop-all

ws-stop-all stops all emacs web servers by mapping ws-stop over ws-servers.

5.3 Convenience Functions

The following convenience functions automate many common tasks associated with responding to HTTP requests.

Function: ws-response-header process code &rest headers

Send the headers required to start an HTTP response to proc. proc should be a ws-request proc of an active request.

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 proc using 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 ("Content-Encoding" . "gzip"), any data subsequently written to proc using ws-send will be compressed using the command specified in ws-gzip-cmd. See Gzipped Transfer Encoding and Chunked Transfer Encoding for more complete examples.

Function: ws-send proc string

Send string to process proc. If any Content or Transfer encodings are in use, apply them to string before sending.

Function: ws-send-500 process &rest msg-and-args

ws-send-500 sends a default 500 “Internal Server Error” response to process.

Function: ws-send-404 process &rest msg-and-args

ws-send-500 sends a default 404 “File Not Found” response to process.

Function: ws-send-file process path &optional mime-type

ws-send-file sends the file located at path to process. If the optional mime-type is not set, then the mime-type is determined by calling mm-default-file-encoding on path or is set to “application/octet-stream” if no mime-type can be determined.

Function: ws-send-directory-list process directory &optional match

ws-send-directory-list sends the a listing of the files located in directory to 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 listed.

Function: ws-in-directory-p parent path

Check if path is under the parent directory.

(ws-in-directory-p "/tmp/" "pics")
    ⇒ "/tmp/pics"

(ws-in-directory-p "/tmp/" "..")
    ⇒ nil

(ws-in-directory-p "/tmp/" "~/pics")
    ⇒ nil

Function: ws-with-authentication handler credentials &optional realm unauth invalid

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")))))

Function: ws-web-socket-connect request handler

If 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>>

5.4 Customization Variables

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.

Variable: ws-compress-cmd

Command used for the “compress” Content or Transfer coding.

Variable: ws-deflate-cmd

Command used for the “deflate” Content or Transfer coding.

Variable: ws-gzip-cmd

Command used for the “gzip” Content or Transfer coding.