Permalink
Browse files

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

  • Loading branch information...
2 parents ed75b53 + f7d145c commit a8d2b52d9e9b14defd04d488cf93f782c298ede5 @klacke committed Jun 24, 2012
View
@@ -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
View
@@ -340,7 +340,12 @@
}).
-
+%% forward and reverse proxy config info
+-record(proxy_cfg, {
+ prefix,
+ url,
+ intercept_mod
+ }).
View
@@ -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
Oops, something went wrong.

0 comments on commit a8d2b52

Please sign in to comment.