[elpa] 47/119: even more documentation and examples

[Eric Schulte]

eschulte pushed a commit to branch master
in repository elpa.

commit d1ad64c02c409376e9c002e8a2672bec1d1b9e0c
Author: Eric Schulte <address@hidden>
Date:   Thu Dec 26 13:17:59 2013 -0700

    even more documentation and examples
    
      and an improved in-directory testing function
---
 doc/emacs-web-server.texi |  164 ++++++++++++++++++++++++++++++++++-----------
 emacs-web-server-test.el  |   11 +++
 emacs-web-server.el       |   15 ++---
 3 files changed, 141 insertions(+), 49 deletions(-)

diff --git a/doc/emacs-web-server.texi b/doc/emacs-web-server.texi
index 30d79cf..4649474 100644
--- a/doc/emacs-web-server.texi
+++ b/doc/emacs-web-server.texi
@@ -43,7 +43,7 @@ A copy of the license is included in the section entitled
 @menu
 * Introduction::                Overview of the Emacs Web Server
 * Handlers::                    Handlers respond to HTTP requests
-* Request::                     Getting information on HTTP requests
+* Requests::                     Getting information on HTTP requests
 * Usage Examples::              Examples demonstrating usage
 * Function Index::              List of Functions
 
@@ -68,7 +68,7 @@ Appendices
 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{Request}) which holds information about the
+request object (@pxref{Requests}) which holds information about the
 request and the process holding HTTP network connection.  Handlers
 write their responses directly to the network process.
 
@@ -76,7 +76,7 @@ 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}).
 
address@hidden Handlers, Request, Handlers, Top
address@hidden Handlers, Requests, Handlers, Top
 @chapter Handlers
 @cindex handlers
 
@@ -86,6 +86,7 @@ The function @code{ews-start} takes takes two arguments
 association list composed of pairs of matchers and handler functions.
 
 @section Matchers
address@hidden matchers
 
 Matchers may be a regular expression or a function.  Regular
 expression matchers consists of an HTTP header and a regular
@@ -99,7 +100,7 @@ whose path starts with the substring ``foo''.
 @end example
 
 A function matcher is a function which takes the request object
-(@pxref{Request}) and succeeds when the function returns a non-nil
+(@pxref{Requests}) and succeeds when the function returns a non-nil
 value.  For example the following matcher matches every request,
 
 @example
@@ -114,10 +115,11 @@ and the following matches only requests in which the 
supplied
   (oddp (string-to-number (cdr (assoc "number" request)))))
 @end example
 
address@hidden Handler
address@hidden Handler Function
address@hidden handler function
 
 Each handler is a function which takes a request object
-(@pxref{Request}) as its only argument.  The function may respond to
+(@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
@@ -130,20 +132,21 @@ to a request as in the following.
 When the handler function exits the connection is terminated unless
 the handler function returns the keyword @code{:keep-alive}.
 
address@hidden Request, Usage Examples, Handlers, Top
address@hidden Request
address@hidden request
address@hidden Requests, Usage Examples, Handlers, Top
address@hidden Requests
address@hidden requests
 
-Each HTTP requests is represented using a @code{request} object.  The
-request object is used to decide which handler to call, and is passed
-as an argument to the called handler.  The request object holds the
-network process, all HTTP headers, and any parameters.
+Each HTTP requests is represented using an @code{ews-request} object
+(@pxref{ews-request}).  The request object is used to decide which
+handler to call, and is passed as an argument to the called handler.
+The request object holds the network process, all HTTP headers, and
+any parameters.
 
 The text of the request is parsed into an 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.
 
address@hidden Usage Examples, Hello World, Request, Top
address@hidden Usage Examples, Hello World, Requests, Top
 @chapter Usage Examples
 @cindex usage examples
 
@@ -229,41 +232,117 @@ in a @code{POST} request.
 
 The following functions implement the Emacs Web Server public API.
 
-To start and stop servers, use the following functions.
address@hidden Objects
+The following objects represent web servers and requests.
+
address@hidden
address@hidden Class ews-server handlers process port requests
+Every Emacs web server is an instance of the @code{ews-server} class.
+Each instance includes the @code{handlers} association list and
address@hidden passed to @code{ews-start}, as well as the server network
address@hidden and a list of all active @code{requests}.
address@hidden deftp
+
address@hidden
address@hidden Class ews-request process pending context boundary headers
+The @code{ews-request} class represents an active web request.  The
address@hidden field holds the network process of the client machine
+and may be used by handlers to respond to requests.  The
address@hidden field holds an alist of information on the request for
+use by handlers.  The remaining @code{pending}, @code{context} and
address@hidden fields are used to maintain header parsing information
+across calls to the @code{ews-filter} function.
address@hidden deftp
+
address@hidden Starting and Stopping Servers
address@hidden start and stop
+The following functions start and stop Emacs web servers.  The
address@hidden list holds all running servers.
+
address@hidden
address@hidden ews-start handlers port &optional log-buffer &rest network-args
address@hidden starts a server listening on @code{port} using
address@hidden (@pxref{Handlers}) to match and respond to requests.
+An instance of the @code{ews-server} class is returned.
address@hidden defun
+
address@hidden
address@hidden ews-servers
+The @code{ews-servers} list holds all active Emacs web servers.
address@hidden defvar
+
address@hidden
address@hidden ews-stop server
address@hidden stops @code{server} deletes all related processes, and
+frees the server's port.  Evaluate the following to stop all emacs web
+servers.
address@hidden
+(mapc #'ews-stop ews-servers)
address@hidden example
address@hidden defun
 
address@hidden
address@hidden ews-start
address@hidden ews-stop
address@hidden itemize
address@hidden Convenience Functions
+The following convenience functions automate many common tasks
+associated with responding to HTTP requests.
 
-All running servers are stored in the @code{ews-servers} variable.
address@hidden
address@hidden content type
address@hidden ews-response-header process code &rest header
+Send the headers required to start an HTTP response to @code{process}.
address@hidden should be a @code{ews-request} @code{process} of an
+active request.  For example start a standard 200 ``OK'' HTML response
+with the following.
 
address@hidden
address@hidden ews-servers
address@hidden itemize
address@hidden
+(ews-response-header process 200 '("Content-type" . "text/html"))
address@hidden example
 
-Each ews-server is an instance of the @code{ews-server} class.
+The encoding may optionally be set in the HTTP header.  Send a UTF8
+encoded response with the following.
 
address@hidden
address@hidden ews-server
address@hidden itemize
address@hidden
+(ews-response-header process 200
+            '("Content-type" . "text/plain; charset=utf-8"))
address@hidden example
 
-Each request object is an instance of the @code{ews-client} class.
address@hidden defun
+
address@hidden
address@hidden ews-send-500 process &rest msg-and-args
address@hidden sends a default 500 ``Internal Server Error''
+response to @code{process}.
address@hidden defun
+
address@hidden
address@hidden ews-send-404 process &rest msg-and-args
address@hidden sends a default 404 ``File Not Found'' response to
address@hidden
address@hidden defun
+
address@hidden
address@hidden ews-send-file process path &optional mime-type
address@hidden sends the file located at @code{path} to
address@hidden  If the optional @code{mime-type} is not set, then the
+mime-type is determined by calling @code{mm-default-file-encoding} on
address@hidden or is set to ``application/octet-stream'' if no mime-type
+can be determined.
address@hidden defun
+
address@hidden
address@hidden ews-in-directory-p parent path
+Check if @code{path} is under the @code{parent} directory.
 
address@hidden
address@hidden ews-request
address@hidden itemize
address@hidden
+(ews-in-directory-p "/tmp/" "pics")
+    @result{} "/tmp/pics"
 
-The following convenience functions automate many common tasks
-associated with responding to HTTP requests.
+(ews-in-directory-p "/tmp/" "..")
+    @result{} nil
 
address@hidden
address@hidden ews-response-header
address@hidden ews-send-500
address@hidden ews-send-404
address@hidden ews-send-file
address@hidden ews-subdirectoryp
address@hidden itemize
+(ews-in-directory-p "/tmp/" "~/pics")
+    @result{} nil
address@hidden example
address@hidden defun
 
 @node Copying, GNU Free Documentation License, Function Index, Top
 @appendix GNU GENERAL PUBLIC LICENSE
@@ -276,6 +355,11 @@ associated with responding to HTTP requests.
 @node Index,  , GNU Free Documentation License, Top
 @unnumbered Index
 
address@hidden Combine all index (function variable type and concept) types 
into a
address@hidden single index.
address@hidden fn cp
address@hidden vr cp
address@hidden tp cp
 @printindex cp
 
 @bye
diff --git a/emacs-web-server-test.el b/emacs-web-server-test.el
index aa80442..6255ee6 100644
--- a/emacs-web-server-test.el
+++ b/emacs-web-server-test.el
@@ -179,4 +179,15 @@ 
org=-+one%0A-+two%0A-+three%0A-+four%0A%0A&beg=646&end=667&path=%2Fcomplex.org")
     (should (string= (ews-test-curl-to-string "" nil '(("message" . "foo")))
                      "you said \"foo\"\n"))))
 
+(ert-deftest ews/in-directory-p ()
+  (should-not (ews-in-directory-p "/tmp/" "foo/bar/../../../"))
+  (should     (ews-in-directory-p "/tmp/" "foo/bar/../../../tmp/baz"))
+  (should     (ews-in-directory-p "/tmp/" "./"))
+  (should-not (ews-in-directory-p "/tmp/" "/~/pics"))
+  (should-not (ews-in-directory-p "/tmp/" "~/pics"))
+  (should-not (ews-in-directory-p "/tmp/" "/pics"))
+  (should-not (ews-in-directory-p "/tmp/" "../pics"))
+  (should     (ews-in-directory-p "/tmp/" "pics"))
+  (should-not (ews-in-directory-p "/tmp/" "..")))
+
 (provide 'emacs-web-server-test)
diff --git a/emacs-web-server.el b/emacs-web-server.el
index 29838f9..41d87fe 100644
--- a/emacs-web-server.el
+++ b/emacs-web-server.el
@@ -293,16 +293,13 @@ Optionally explicitly set MIME-TYPE, otherwise it is 
guessed by
         (insert-file-contents-literally path)
         (buffer-string)))))
 
-(defun ews-subdirectoryp (parent path)
-  "Check that PATH is a subdirectory of PARENT.
+(defun ews-in-directory-p (parent path)
+  "Check if PATH is under the PARENT directory.
 If so return PATH, if not return nil."
-  (let* ((expanded (expand-file-name path))
-         (complete (if (string= (substring expanded -1) "/")
-                       expanded
-                     (concat expanded "/"))))
-    (and (>= (length complete) (length parent))
-         (string= parent (substring complete 0 (length parent)))
-         complete)))
+  (let ((expanded (expand-file-name path parent)))
+    (and (>= (length expanded) (length parent))
+         (string= parent (substring expanded 0 (length parent)))
+         expanded)))
 
 (provide 'emacs-web-server)
 ;;; emacs-web-server.el ends here