Merge branch 'master' of github.com:klacke/yaws

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

include/yaws.hrl

@@ -340,7 +340,12 @@
          }).
 
 
-
+%% forward and reverse proxy config info
+-record(proxy_cfg, {
+          prefix,
+          url,
+          intercept_mod
+         }).
 
 
 

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