[master] 2ad850a document a non-GET caching killer and test the workaround

[Nils Goroll]

commit 2ad850a87bf74c2bf54bf6143e5c2dc941b18673
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Thu Sep 15 08:13:56 2016 +0200

    document a non-GET caching killer and test the workaround

diff --git a/bin/varnishtest/tests/r01927.vtc b/bin/varnishtest/tests/r01927.vtc
index e981521..c6769df 100644
--- a/bin/varnishtest/tests/r01927.vtc
+++ b/bin/varnishtest/tests/r01927.vtc
@@ -13,6 +13,7 @@ server s1 {
 
 varnish v1 -vcl+backend {
 	sub vcl_recv {
+		set req.http.X-Method = req.method;
 		# We ignore the actual body and verb for this test.
 		return (hash);
 	}
@@ -20,7 +21,8 @@ varnish v1 -vcl+backend {
 		return (fetch);
 	}
 	sub vcl_backend_fetch {
-		set bereq.method = "POST";
+		set bereq.method = bereq.http.X-Method;
+		unset bereq.http.X-Method;
 		set bereq.first_byte_timeout = 1s;
 	}
 	sub vcl_backend_response {
diff --git a/doc/sphinx/whats-new/changes-5.0.rst b/doc/sphinx/whats-new/changes-5.0.rst
index adc6247..b8682db 100644
--- a/doc/sphinx/whats-new/changes-5.0.rst
+++ b/doc/sphinx/whats-new/changes-5.0.rst
@@ -142,16 +142,21 @@ requests because it is questionable if GET with a body is valid anyway
 So the often-requested ability to cache POST/PATCH/... is now available,
 but not out-of-the-box:
 
-The ``builtin.vcl`` still contains a ``return(pass)`` for anything but
-a GET or HEAD because other HTTP methods, by definition, may cause
-state changes / side effects on backends. The application at hand
-should be understood well before caching of non-GET/non-HEAD is
-considered.
-
-Care should be taken to choose an appropriate cache key and/or Vary
-criteria. Adding the request body to the cache key is not possible
-with core varnish, but through a VMOD
-https://github.com/aondio/libvmod-bodyaccess
+* The ``builtin.vcl`` still contains a ``return(pass)`` for anything
+  but a GET or HEAD because other HTTP methods, by definition, may cause
+  state changes / side effects on backends. The application at hand
+  should be understood well before caching of non-GET/non-HEAD is
+  considered.
+
+* For misses, core code still calls the equivalent of ``set
+  bereq.method = "GET"`` before calling ``vcl_backend_fetch``, so to
+  make a backend request with the original request method, it needs to
+  saved in ``vcl_recv`` and restored in ``vcl_backend_fetch``.
+
+* Care should be taken to choose an appropriate cache key and/or Vary
+  criteria. Adding the request body to the cache key is not possible
+  with core varnish, but through a VMOD
+  https://github.com/aondio/libvmod-bodyaccess
 
 To summarize: You should know what you are doing when caching anything
 but a GET or HEAD and without creating an appropriate cache key doing