[master] 0a0de58 try to summarize request body handling and non-GET caching

[Nils Goroll]

commit 0a0de584b41d3e3cc11e62e1d9df110c4150a87e
Author: Nils Goroll <nils.goroll at uplex.de>
Date:   Wed Sep 14 13:03:48 2016 +0200

    try to summarize request body handling and non-GET caching

diff --git a/doc/changes.rst b/doc/changes.rst
index d26b7bd..bea3095 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -15,8 +15,8 @@ Major items:
 
 * (Very!) experimental support for HTTP/2.
 
-* Always send the request body to the backend, making possible to cache
-  POST, PUT, PATCH etc.
+* Always send the request body to the backend, allowing caching of
+  POST, PUT, PATCH etc with appropriate custom VCL and/or vmods.
 
 * hit-for-pass is now actually hit-for-miss.
 
diff --git a/doc/sphinx/whats-new/changes-5.0.rst b/doc/sphinx/whats-new/changes-5.0.rst
index 8ad3b19..57223a5 100644
--- a/doc/sphinx/whats-new/changes-5.0.rst
+++ b/doc/sphinx/whats-new/changes-5.0.rst
@@ -128,6 +128,37 @@ obj.ttl, obj.age, obj.grace and obj.keep are now available vcl_deliver
 read-only.
 
 
+Request Body sent always / "cacheable POST"
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Previously, we would only send a request body for passed requests (and
+for pipe mode, but this is special anyway and should be avoided).
+
+Not so any more, but the default behaviour has not changed:
+
+Whenever a request has a body, it will get sent to the backend for a
+cache miss (and pass, as before). This can be prevented by an unset
+bereq.body and the builtin.vcl removes the body for GET requests
+because it is questionable if GET with a body is valid anyway (but
+some applications use it).
+
+So the often-requested ability to cache POST/PUT/... 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 punchline: You should know what you are doing when caching
+anything but a GET or HEAD and without creating an appropriate cache
+key doing so is almost guaranteed to be wrong.
+
 News for vmod authors
 ~~~~~~~~~~~~~~~~~~~~~