[4.1] c9598de document bereq preparation in core

PÃ¥l Hermunn Johansen hermunn at varnish-software.com
Thu Oct 13 10:56:04 CEST 2016

commit c9598debac3407add0ab084313f2f63a7fc09c9d
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Tue Oct 4 17:14:40 2016 +0200

    document bereq preparation in core
    (Backport of 2bbcde1d with the fix b698aec2 squashed in)
    doc fixes #2107

diff --git a/doc/sphinx/users-guide/vcl-built-in-subs.rst b/doc/sphinx/users-guide/vcl-built-in-subs.rst
index 21e5873..0128233 100644
--- a/doc/sphinx/users-guide/vcl-built-in-subs.rst
+++ b/doc/sphinx/users-guide/vcl-built-in-subs.rst
@@ -271,6 +271,34 @@ The `vcl_backend_fetch` subroutine may terminate with calling
     background fetch, control is passed to :ref:`vcl_synth` on the
     client side with ``resp.status`` preset to 503.
+Before calling `vcl_backend_fetch`, varnish core prepares the `bereq`
+backend request as follows:
+* Unless the request is a `pass`,
+  * set ``bereq.method`` to ``GET`` and ``bereq.proto`` to
+    ``HTTP/1.1`` and
+  * set ``bereq.http.Accept_Encoding`` to ``gzip`` if
+    :ref:`ref_param_http_gzip_support` is enabled.
+* If there is an existing cache object to be revalidated, set
+  ``bereq.http.If-Modified-Since`` from its ``Last-Modified`` header
+  and/or set ``bereq.http.If-None-Match`` from its ``Etag`` header
+* Set ``bereq.http.X-Varnish`` to the current transaction id (`vxid`)
+These changes can be undone or modified in `vcl_backend_fetch` before
+the backend request is issued.
+In particular, to cache non-GET requests, ``req.method`` needs to be
+saved to a header or variable in :ref:`vcl_recv` and restored to
+``bereq.method``. Notice that caching non-GET requests typically also
+requires changing the cache key in :ref:`vcl_hash` e.g. by also
+hashing the request method and/or request body.
+HEAD request can be satisfied from cached GET responses.
 .. _vcl_backend_response:

More information about the varnish-commit mailing list