[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
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
@@ -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.
More information about the varnish-commit