add reverse proxy intercept module capability

Users can now specify an interception module that can rewrite requests and responses as they pass through the Yaws reverse proxy. See the documentation for details (yaws.conf.5 man page or the yaws.pdf file). Also add new set_header, get_header, and delete_header functions to the yaws_api module to allow intercept modules and arg rewriters to more easily examine and modify #headers{} records. Add new tests for the new header manipulation functions and for the reverse proxy interception feature.
GokulEvuri · Jun 21, 2012 · cccc578 · cccc578
1 parent 92a1a27
commit cccc578
Show file tree

Hide file tree

Showing 16 changed files with 679 additions and 124 deletions.
diff --git a/doc/yaws.tex b/doc/yaws.tex
@@ -1218,6 +1218,18 @@ \subsection{Arg rewrite}
 argument so that the login page can redirect the user to the original
 page once the login procedure is finished.
 
+Within an arg rewrite function, examining and modifying HTTP headers can be
+achieved using the following functions from the \verb+yaws_api+ module:
+
+\begin{itemize}
+\item \verb+set_header/2+, \verb+set_header/3+
+\item \verb+get_header/2+, \verb+get_header/3+
+\item \verb+delete_header/2+
+\end{itemize}
+
+All functions operate on instances of the \verb+#headers{}+ record type
+defined in the \verb+yaws_api.hrl+ include file.
+
 \subsection{Authenticating}
 
 Now we're approaching the \verb+login.yaws+ page, the page that
@@ -2697,17 +2709,64 @@ \section{Server Part}
               specific configuration data, see the explanation for the
               \verb+<opaque>+ context.
 
-\item       \verb+revproxy = Prefix Url+ ---
+\item       \verb+revproxy = Prefix Url [intercept_mod Module]+ ---
               Make \Yaws\ a reverse proxy. \verb+Prefix+ is a path inside our own
               docroot and \verb+Url+ is a URL pointing to a website we
-              want to "mount" under the path which is \verb+Prefix+.
+              want to "mount" under the \verb+Prefix+ path. For example:
 
-              Example: \verb+revproxy = /tmp/foo http://yaws.hyber.org+
+              \verb+revproxy = /tmp/foo http://yaws.hyber.org+
 
               This makes the hyber website appear under \verb+/tmp/foo+.
 
               It is possible to have multiple reverse proxies inside the same
-              server.
+              server by supplying multiple \verb+revproxy+ directives.
+
+              If the optional keyword \verb+intercept_mod+ and
+              \verb+Module+ are supplied in the \verb+revproxy+ directive,
+              then \verb+Module+ indicates a proxy request and response
+              interception module. When the reverse proxy receives a
+              request from a client, it will first pass
+              \verb+#http_request{}+ and \verb+#headers{}+ records
+              representing the client request to the intercept module's
+              \verb+rewrite_request/2+ function. The function must return a
+              3-tuple of the following form:
+
+\begin{verbatim}
+{ok, #http_request{}, #headers{}}
+\end{verbatim}
+
+              where the record instances can be the original values passed
+              in or new values. The reverse proxy will use these record
+              instances when passing the request to the backend server.
+
+              Similarly, when the backend server returns a response, the
+              reverse proxy will call the intercept module's
+              \verb+rewrite_response/2+ function, passing it an
+              \verb+#http_response{}+ record and a \verb+#headers{}+
+              record. The function must return a 3-tuple of the following
+              form:
+
+\begin{verbatim}
+{ok, #http_response{}, #headers{}}
+\end{verbatim}
+
+              where the record instances can be the original values passed
+              in or new values. The reverse proxy will use these record
+              instances when returning the response to the client.
+
+              Any failure within an intercept module function results in
+              HTTP status code 500 (Internal Server Error) being returned
+              to the client.
+
+              Intercept modules can use the following functions from the
+              \verb+yaws_api+ module to retrieve, set, or delete HTTP
+              headers from \verb+#headers{}+ records:
+
+\begin{itemize}
+\item \verb+set_header/2+, \verb+set_header/3+
+\item \verb+get_header/2+, \verb+get_header/3+
+\item \verb+delete_header/2+
+\end{itemize}
 
 \item       \verb+fwdproxy = true|false+ ---
               Make \Yaws\ a forward proxy. By enabling this option you can use

diff --git a/include/yaws.hrl b/include/yaws.hrl
@@ -340,7 +340,12 @@
          }).
 
 
-
+%% forward and reverse proxy config info
+-record(proxy_cfg, {
+          prefix,
+          url,
+          intercept_mod
+         }).
 
 
 

diff --git a/man/yaws.conf.5 b/man/yaws.conf.5
@@ -150,7 +150,7 @@ of 0 effectively disables the process pool.
 \fBlog_wrap_size = Integer\fR
 The logs written by Yaws are all wrap logs, the default value at the size where
 they wrap around and the original gets renamed to File.old is \fI1000000\fR, 1
-megabyte. This value can changed.
+megabyte. This value can be changed.
 .br
 If we set the value to 0 the logs will never wrap. If we want to use Yaws in
 combination with a more traditional log wrapper such as logrotate, set the size
@@ -667,27 +667,69 @@ synchronize the startup with the Yaws server as well as getting hold of user
 specific configuration data, see the explanation for the <opaque> context.
 
 .TP
-\fBrevproxy = Prefix Url\fR
-Make Yaws a reverse proxy. The Prefix is a path inside our own docroot and the
-Url argument is an url pointing to a website we want to "mount" under the path
-which is Prefix.
+\fBrevproxy = Prefix Url [intercept_mod Module]\fR
+Make Yaws a reverse proxy. \fIPrefix\fR is a path inside our own docroot
+and \fIUrl\fB argument is a URL pointing to a website we want to "mount"
+under the \fIPrefix\fR path. This example:
 
-Example: revproxy = /tmp/foo http://yaws.hyber.org
+.nf
+  revproxy = /tmp/foo http://yaws.hyber.org
+.fi
 
-Makes the hyber website appear under /tmp/foo
+makes the hyber website appear under \fI/tmp/foo\fR.
 
 It is possible to have multiple reverse proxies inside the same server.
 
-WARNING, this feature is yet not in production quality.
+You can optionally configure an interception module for each reverse proxy,
+allowing your application to examine and modify requests and HTTP headers
+as they pass through the proxy from client to backend server and also
+examine and modify responses and HTTP headers as they return from the
+backend server through the proxy to the client.
+
+You specify an interception module by including the optional
+\fIintercept_mod\fR keyword followed by \fIModule\fR, which should be the
+name of your interception module.
+
+An interception module is expected to export two functions:
+\fIrewrite_request/2\fR and \fIrewrite_response/2\fR. The two arguments
+passed to \fIrewrite_request/2\fR function are a \fI#http_request{}\fR record
+and a \fI#headers{}\fR record, whereas \fIrewrite_response/2\fR function
+takes a \fI#http_response{}\fR record and also a \fI#headers{}\fR record. You
+can find definitions for these record types in the \fIyaws_api.hrl\fR
+header file. Each function can examine each record instance and can either
+return each original instance or can return a modified copy of each
+instance in its response. The \fIrewrite_request/2\fR function should
+return a tuple of the following form:
+
+.nf
+  \fI{ok, #http_request{}, #headers{}}\fR
+.fi
+
+and the \fIrewrite_response/2\fR function should similarly return a tuple
+of the following form:
+
+.nf
+  \fI{ok, #http_response{}, #headers{}}\fR
+.fi
+
+A \fI#headers{}\fR record can easily be manipulated in an interceptor using
+the functions listed below:
+
+.nf
+  \fIyaws_api:set_header/2\fR, \fIyaws_api:set_header/3\fR
+  \fIyaws_api:get_header/2\fR, \fIyaws_api:get_header/3\fR
+  \fIyaws_api:delete_header/2\fR
+.fi
+
+Any failures in your interception module's functions will result in HTTP
+status code 500, indicating an internal server error.
 
 .TP
 \fBfwdproxy = true|false\fR
 Make Yaws a forward proxy. By enabling this option you can use Yaws as a proxy
 for outgoing web traffic, typically by configuring the proxy settings in a
 web-browser to explicitly target Yaws as its proxy server.
 
-WARNING, this feature is yet not in production quality.
-
 .TP
 \fBservername = Name\fR
 If we're virthosting everal servers and want to force a server to match specific
-Original file line number
+Diff line change
@@ Expand Up / @@ -340,7 +340,12 @@ @@
              }).
+    %% forward and reverse proxy config info
+    -record(proxy_cfg, {
+              prefix,
+              url,
+              intercept_mod
+             }).
@@ Expand Down @@