eschulte pushed a commit to branch master
in repository elpa.
commit 11e50b506e54d7190e4e9bb547e0a35f54f3cf7e
Author: Eric Schulte <schulte.e...@gmail.com>
Date: Wed Feb 12 17:08:20 2014 -0700
doc for new content/transfer encoding helpers
---
NOTES | 4 +-
doc/web-server.texi | 77 ++++++++++++++++++++++++++--
examples/016-content-encoding-gzip.el | 2 +-
examples/017-transfer-encoding-chunked.el | 2 +-
web-server.el | 13 ++++-
5 files changed, 86 insertions(+), 12 deletions(-)
diff --git a/NOTES b/NOTES
index 00febfb..e086b93 100644
--- a/NOTES
+++ b/NOTES
@@ -4,8 +4,8 @@
#+Options: ^:{}
* Notes
-* Tasks [17/21]
-** TODO Content and Transfer encodings
+* Tasks [18/21]
+** DONE Content and Transfer encodings
- Content and Transfer encoding values
http://www.iana.org/assignments/http-parameters/http-parameters.xhtml
- http://www.w3.org/Protocols/rfc2616/rfc2616-sec3.html#sec3.6
diff --git a/doc/web-server.texi b/doc/web-server.texi
index e86ff93..0ae094b 100644
--- a/doc/web-server.texi
+++ b/doc/web-server.texi
@@ -191,6 +191,8 @@ These examples demonstrate usage.
* 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
@@ -313,7 +315,7 @@ $ sha1sum /usr/share/emacs/24.3/etc/COPYING
8624bcdae55baeef00cd11d5dfcfa60f68710a02 /usr/share/emacs/24.3/etc/COPYING
@end example
-@node Web Socket, Function Index, File Upload, Usage Examples
+@node Web Socket, Chunked Transfer Encoding, File Upload, Usage Examples
@section Web Socket
Example demonstrating the use of web sockets for full duplex
@@ -340,6 +342,28 @@ 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
@@ -407,11 +431,13 @@ associated with responding to HTTP requests.
@anchor{ws-response-header}
@cindex content type
-@defun ws-response-header process code &rest header
-Send the headers required to start an HTTP response to @code{process}.
-@code{process} should be a @code{ws-request} @code{process} of an
-active request. For example start a standard 200 ``OK'' HTML response
-with the following.
+@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"))
@@ -425,6 +451,24 @@ encoded response with the following.
'("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}
@@ -515,6 +559,27 @@ socket messages received from the client.
@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
diff --git a/examples/016-content-encoding-gzip.el
b/examples/016-content-encoding-gzip.el
index 7a56eb1..e50bf58 100644
--- a/examples/016-content-encoding-gzip.el
+++ b/examples/016-content-encoding-gzip.el
@@ -1,4 +1,4 @@
-;;; content-encoding-gzip.el -- manual application of gzip content encoding
+;;; content-encoding-gzip.el -- gzip content encoding
(ws-start
(lambda (request)
(with-slots (process headers) request
diff --git a/examples/017-transfer-encoding-chunked.el
b/examples/017-transfer-encoding-chunked.el
index 1ec92ed..3217ccf 100644
--- a/examples/017-transfer-encoding-chunked.el
+++ b/examples/017-transfer-encoding-chunked.el
@@ -1,4 +1,4 @@
-;;; transfer-encoding-chunked.el -- manual chunked transfer encoding
+;;; transfer-encoding-chunked.el -- chunked transfer encoding
(ws-start
(lambda (request)
(let ((s "
diff --git a/web-server.el b/web-server.el
index 4e885f0..1943f95 100644
--- a/web-server.el
+++ b/web-server.el
@@ -537,8 +537,17 @@ See RFC6455."
;;; Convenience functions to write responses
(defun ws-response-header (proc code &rest headers)
"Send the headers for an HTTP response to PROC.
-Currently CODE should be an HTTP status code, see
-`ws-status-codes' for a list of known codes."
+CODE should be an HTTP status code, see `ws-status-codes' for a
+list of known codes.
+
+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'."
;; update process to reflect any Content or Transfer encodings
(let ((content (cdr (assoc "Content-Encoding" headers)))
(transfer (cdr (assoc "Transfer-Encoding" headers))))
