Update the docs for VCL 4.0

2 files changed, 102 insertions, 23 deletions

diff --git a/doc/vmod-dbrw.3 b/doc/vmod-dbrw.3
index 89b56d6..f2ee5fe 100644
--- a/doc/vmod-dbrw.3
+++ b/doc/vmod-dbrw.3
@@ -10,13 +10,13 @@
 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 .\" GNU General Public License for more details.
 .\"
 .\" You should have received a copy of the GNU General Public License
 .\" along with vmod-dbrw.  If not, see <http://www.gnu.org/licenses/>.
-.TH VMOD-DBRW 1 "November 1, 2014" "VMOD-DBRW" "User Reference"
+.TH VMOD-DBRW 1 "November 12, 2014" "VMOD-DBRW" "User Reference"
 .SH NAME
 vmod-dbrw \- Database-driven rewrite rules for Varnish Cache
 .SH SYNOPSIS
 .B import dbrw;
 .PP
 .BI "VOID dbrw.config(STRING " dbtype ", STRING " params ", STRING " query ");"
@@ -108,23 +108,23 @@ Database user name.
 Password to access the database.
 .PP
 Once configured, the \fBrewrite\fR function can be called in the
 appropriate place of the Varnish configuration file.  Its argument
 \fIargs\fR is a list of variable assignments separated with
 semicolons, similarly to the \fIparams\fR argument described above.
-Each assignment has the form \fINAME\fB=\fIVALUE\fR.  When called
-the function expands the \fBSQL\fR query, supplied with the \fIquery\fR
+Each assignment has the form \fINAME\fB=\fIVALUE\fR.  When called,
+the function expands the \fBSQL\fR query supplied with the \fIquery\fR
 argument to the \fBconfig\fR call, by replacing each \fB$\fINAME\fR
 construct (a \fBvariable reference\fR) with the corresponding
 \fIVALUE\fR from its argument.  Similarly to the shell syntax, the
-variable reference can be written as \fB${\fINAME\fB}\fR.  This latter
+variable reference can be written as \fB${\fINAME\fB}\fR.  This
 form can be used in contexts where the variable name is immediately
 followed by another letter, to prevent it from being counted as a part
 of the name.
 .PP
-The expanded query is then sent to the database server.  The handling
+The expanded query is then sent to the database server.  Handling
 of the return value depends on the number of fields it contains.
 .SS Strict matches
 If the returned set consists of one or two columns, only the
 first tuple is used and the value of its first column is returned.
 The second column (if present) is ignored.
 .SS Regexp matches
@@ -184,13 +184,13 @@ CREATE TABLE redirects (
     url varchar(255) NOT NULL DEFAULT '',
     dest varchar(255) DEFAULT NULL,
     PRIMARY KEY (host,url)
 );
 .EE
 .PP
-VCL code:
+VCL 3.0 code:
 .PP
 .EX
 sub vcl_init {
     dbrw.config("mysql", "database=dbname;user=varnish",
                 {"SELECT dest
                     FROM redirects
@@ -215,12 +215,40 @@ sub vcl_error {
     }
 }
 .EE
 .PP
 Notice the use of concatenation to build the argument to
 \fBdbrw.rewrite\fR.
+.PP
+The following is the same code for VCL 4.0:
+.PP
+.EX
+sub vcl_init {
+    dbrw.config("mysql", "database=dbname;user=varnish",
+                {"SELECT dest
+                    FROM redirects
+                   WHERE host='$host'
+                     AND url='$url'"});
+}
+
+sub vcl_recv {
+    set req.http.X-Redirect-To =
+        dbrw.rewrite("host=" + req.http.Host + ";" +
+                     "url=" + req.url);
+    if (req.http.X-Redirect-To != "") {
+        return(synth(301, "Redirect"));
+    }
+}
+
+sub vcl_synth {
+    if (resp.status == 301) {
+        set resp.http.Location = req.http.X-Redirect-To;
+        return (deliver);
+    }
+}
+.EE
 .SS Rewrites
 .PP
 The database structure is as follows:
 .PP
 .EX
 CREATE TABLE rewrite (
@@ -231,13 +259,13 @@ CREATE TABLE rewrite (
     pattern varchar(255) DEFAULT NULL,
     flags char(64) DEFAULT NULL,
     KEY source (host,url)
 )
 .EE
 .PP
-VCL code:
+VCL 3.0 code:
 .PP
 .EX
 import std;
 import dbrw;
 
 sub vcl_init {
@@ -270,23 +298,44 @@ sub vcl_error {
         set obj.http.Location = req.http.X-Redirect-To;
         set obj.status = std.integer(req.http.X-VMOD-DBRW-Status, 301);
         return (deliver);
     }
 }
 .EE
+.PP
+For VCL 4.0, \fBvcl_synth\fR is used instead of \fBvcl_error\fR:
+.PP
+.EX
+sub vcl_recv {
+    set req.http.X-Redirect-To =
+        dbrw.rewrite("host=" + req.http.Host + ";" +
+                     "url=" + req.url);
+    if (req.http.X-Redirect-To != "") {
+        return(synth(750, "Redirect"));
+    }
+}
+
+sub vcl_synth {
+    if (resp.status == 750) {
+        set obj.status = std.integer(req.http.X-VMOD-DBRW-Status, 301);
+        set resp.http.Location = req.http.X-Redirect-To;
+        return (deliver);
+    }
+}
+.EE
 .SS Use of vmod-dbrw and vmod-redirect
 .PP
 .ie "\*[.T]"html" \{\
-Using the
+For VCL 3.0 you can use the
 .URL https://www.varnish-cache.org/vmod/redirect \fBvmod-redirect\fR " module"
 \}
 .el \{\
-Using the \fBvmod-redirect\fR module
+For VCL 3.0 you can use the \fBvmod-redirect\fR module
 .BR ( https://www.varnish-cache.org/vmod/redirect )
 \}
-you can get rid of the \fBvcl_error\fR subroutine:
+and get rid of the \fBvcl_error\fR subroutine:
 .PP
 .EX
 import std;
 import dbrw;
 import redirect;
 
diff --git a/doc/vmod-dbrw.texi b/doc/vmod-dbrw.texi
index e399a84..344b940 100644
--- a/doc/vmod-dbrw.texi
+++ b/doc/vmod-dbrw.texi
@@ -100,26 +100,28 @@ module in @command{Apache} or to @code{Redirect} directives of its
 that they are stored in an SQL database, which makes them easily
 manageable.
 
 Some web sites implement thousands of rewrite rules.  The purpose
 of this module is to facilitate deploying and handling them.
 
+The module can be compiled for VCL 3.0 or 4.0.
+
 @node Overview
 @chapter Overview
 @cindex rewrite rules
 @cindex database engines
 @cindex supported databases
-The rewrite rules are stored in a MySQL or PostgreSQL database.  The
+Rewrite rules are stored in a MySQL or PostgreSQL database.  The
 @command{vmod-dbrw} module does not impose any restrictions on its
 schema.  It only needs to know the SQL query which is to be used to
 retrieve data.  This query is supplied to the module, along with the
 credentials for accessing the database, by calling the @code{config}
 function in the @code{vcl_init} subroutine of the Varnish
 configuration file.
 
-Once the module configured, the @code{rewrite} function can be called
+Once the module is configured, the @code{rewrite} function can be called
 in the appropriate place of the Varnish configuration file.  Its argument
 is a list of variable assignments separated with semicolons, each
 assignment having the form @code{@var{name}=@var{value}}.  When called,
 @code{rewrite} expands the SQL query registered with the prior call to
 @code{config} by replacing each @code{$@var{name}}
 construct (a @dfn{variable reference}) with the corresponding
@@ -258,13 +260,13 @@ The following @dfn{escape sequences} are allowed for use in
 @end multitable
 @end float
 
 If a backslash is followed by a symbol other than listed above, it
 is removed and the symbol following it is reproduced verbatim.
 
-The valid parameters are:
+Valid parameters are:
 
 @table @samp
 @kindex debug
 @cindex debugging level
 @item debug=@var{n}
 Set debugging level.  Argument is a decimal number.
@@ -542,55 +544,83 @@ caller.
 @end itemize
 @end deftypefn
 
 @cindex vcl_recv
 Assuming the database structure similar to the one discussed in the
 previous chapter, the following example illustrates how to use
-@code{rewrite} to redirect the incoming request:
+@code{rewrite} to redirect the incoming request.  It assumes VCL 4.0:
 
 @example
 @group
 sub vcl_recv @{
     set req.http.X-Redirect-To =
         dbrw.rewrite("host=" + req.http.Host + ";" +
                      "url=" + req.url);
     if (req.http.X-Redirect-To != "") @{
-        error(750, "Redirect");
+        return(synth(301, "Redirect"));
     @}
 @}
 @end group
 @end example
 
-Further handling of the 750 error should be performed in a traditional
+Further handling of the 301 response should be performed in a traditional
 way, e.g.:
 
 @vindex X-VMOD-DBRW-Status
-@cindex vcl_error
+@cindex vcl_synth
 @cindex vmod_std
 @example
 @group
 import std;
 
+sub vcl_synth @{
+    if (resp.status == 301) @{
+        set resp.http.Location = req.http.X-Redirect-To;
+        if (req.http.X-VMOD-DBRW-Status != "") @{
+            set resp.status =
+               std.integer(req.http.X-VMOD-DBRW-Status, 301);
+        @}
+        return (deliver);
+    @}
+@}
+@end group
+@end example
+
+The @code{X-VMOD-DBRW-Status} header, if set, contains the status code to be
+returned to the client (@pxref{X-VMOD-DBRW-Status}).  Notice the use
+of the @command{vmod_std} module to cast it to integer.
+
+The example below shows the same code for VCL 3.0:
+
+@example
+@group
+import std;
+
+sub vcl_recv @{
+    set req.http.X-Redirect-To =
+        dbrw.rewrite("host=" + req.http.Host + ";" +
+                     "url=" + req.url);
+    if (req.http.X-Redirect-To != "") @{
+        error(750, "Redirect");
+    @}
+@}
+
 sub vcl_error @{
     if (obj.status == 750) @{
         set obj.http.Location = req.http.X-Redirect-To;
         set obj.status =
            std.integer(req.http.X-VMOD-DBRW-Status, 301);
         return (deliver);
     @}
 @}
 @end group
 @end example
 
-The @code{X-VMOD-DBRW-Status} header, if set, contains the status code to be
-returned to the client (@pxref{X-VMOD-DBRW-Status}).  Notice the use
-of the @command{vmod_std} module to cast it to integer.
-
 @cindex vmod_redirect
-Using the @command{vmod_redirect}, the redirection can be further
-simplified:
+For VCL 3.0, you can use @command{libvmod_redirect} to simplify the
+code:
 
 @example
 @group
 import std;
 import dbrw;
 import redirect;