Merge pull request #229 from zghosts/feature/vcl

extract vcl into a reusable set of subroutines

Author: ddeboer

doc/spelling_word_list.txt

@@ -17,3 +17,6 @@ whitelisted
 paywall
 paywalls
 github
+vcl
+fos
+Vcl

doc/varnish-configuration.rst

@@ -33,22 +33,41 @@ will be used throughout the Varnish examples on this page.
     trigger invalidation are whitelisted here. Otherwise, lost cache invalidation
     requests will lead to lots of confusion.
 
+Provided Vcl Subroutines
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+In order to ease configuration we provide a set of vcl subroutines in the resources/config directory.
+These can be directly included into ``your_varnish.vcl`` and the needed subroutines called
+from the respective vcl_* subroutines.
+
+.. important::
+    When including one of the provided vcl you need to call all the defined subroutines
+    or your configuration will not be valid.
+
+    See the respective sections below on how to configure usage of each of the provided vcl's.
+
 Purge
 ~~~~~
 
 To configure Varnish for `handling PURGE requests <https://www.varnish-cache.org/docs/3.0/tutorial/purging.html>`_:
 
 Purge removes a specific URL (including query strings) in all its variants (as specified by the ``Vary`` header).
 
-.. configuration-block::
+Subroutines are provided in ``resources/config/varnis-[version]/fos_purge.vcl``.
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/purge.vcl
-        :language: varnish4
-        :linenos:
+To enable support add the following to ``your_varnish.vcl``:
+
+.. code-block:: varnish3
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/purge.vcl
+    include "path-to-config/varnish-[version]/fos_purge.vcl";
+
+.. configuration-block::
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/fos.vcl
+        :language: varnish4
+        :lines: 17,19,21-22
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/fos.vcl
         :language: varnish3
-        :linenos:
+        :lines: 15,17,19-20,25-32
 
 Refresh
 ~~~~~~~
@@ -58,26 +77,44 @@ add the following to your Varnish configuration:
 
 Refresh invalidates a specific URL including the query string, but *not* its variants.
 
-.. literalinclude:: ../tests/Functional/Fixtures/varnish-3/refresh.vcl
-    :language: varnish3
-    :linenos:
+Subroutines are provided in ``fos_refresh.vcl``
+
+To enable support add the following to ``your_varnish.vcl``:
+
+.. code-block:: varnish3
+
+    include "path-to-config/varnish-[version]/fos_refresh.vcl";
+
+.. configuration-block::
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/fos.vcl
+        :language: varnish4
+        :lines: 17,20-22
+
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/fos.vcl
+        :language: varnish3
+        :lines: 15,18-20
 
 Ban
 ~~~
 
 To configure Varnish for `handling BAN requests <https://www.varnish-software.com/static/book/Cache_invalidation.html#banning>`_:
 
-.. configuration-block::
+Subroutines are provided in ``fos_ban.vcl``
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/ban.vcl
+To enable support add the following to ``your_varnish.vcl``:
+
+.. code-block:: varnish3
+
+    include "path-to-config/varnish-[version]/fos_ban.vcl";
+
+.. configuration-block::
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/fos.vcl
         :language: varnish4
-        :lines: 1-7, 15-18, 20-
-        :linenos:
+        :lines: 17-18,21-29
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/ban.vcl
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/fos.vcl
         :language: varnish3
-        :lines: 1-7, 15-18, 20-
-        :linenos:
+        :lines: 15-16,19-24,33-35
 
 Varnish contains a `ban lurker`_ that crawls the content to eventually throw out banned data even when it’s not requested by any client.
 
@@ -88,23 +125,22 @@ Varnish contains a `ban lurker`_ that crawls the content to eventually throw out
 Tagging
 ~~~~~~~
 
-Add the following to your Varnish configuration to enable :ref:`cache tagging <tags>`.
+If you have included fos_ban.vcl, tagging will be automatically enabled using a ``X-Cache-Tags`` header :ref:`cache tagging <tags>`.
 
 .. note::
-
-    The custom ``X-Cache-Tags`` header should match the tagging header
-    :ref:`configured in the cache invalidator <custom_tags_header>`.
+    If you need to use a different tag for the headers than the default ``X-Cache-Tags`` used in ``fos_ban.vcl``,
+    you need to write your own VCL code and change the tagging header :ref:`configured in the cache invalidator <custom_tags_header>`.
 
 .. configuration-block::
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/ban.vcl
+    .. literalinclude:: ../resources/config/varnish-4/fos_ban.vcl
         :language: varnish4
-        :emphasize-lines: 8-13,39
+        :emphasize-lines: 8-13,40-41
         :linenos:
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/ban.vcl
+    .. literalinclude:: ../resources/config/varnish-3/fos_ban.vcl
         :language: varnish3
-        :emphasize-lines: 8-13,39
+        :emphasize-lines: 8-13,40-41
         :linenos:
 
 .. _varnish user context:
@@ -115,17 +151,22 @@ User Context
 To support :doc:`user context hashing <user-context>` you need to add some logic
 to the ``recv`` and the ``deliver`` methods:
 
-.. configuration-block::
+Subroutines are provided in ``fos_user_context.vcl``.
+
+To enable support add the following to ``your_varnish.vcl``:
 
+.. code-block:: varnish3
+
+    include "path-to-config/varnish-[version]/fos_user_context.vcl";
+
+.. configuration-block::
     .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/user_context.vcl
         :language: varnish4
-        :lines: 3-29, 33-
-        :linenos:
+        :lines: 3-
 
     .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/user_context.vcl
         :language: varnish3
-        :lines: 1-27, 31-
-        :linenos:
+        :lines: 3-
 
 .. sidebar:: Caching User Specific Content
 
@@ -205,15 +246,22 @@ Configure your Varnish to set a custom header (`X-Cache`) that shows whether a
 cache hit or miss occurred. This header will only be set if your application
 sends an `X-Cache-Debug` header:
 
-.. configuration-block::
+Subroutines are provided in ``fos_debug.vcl``.
+
+To enable support add the following to ``your_varnish.vcl``:
+
+.. code-block:: varnish3
+
+    include "path-to-config/varnish-[version]/fos_debug.vcl";
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/debug.vcl
+.. configuration-block::
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-4/user_context.vcl
         :language: varnish4
-        :linenos:
+        :lines: 12,13,15
 
-    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/debug.vcl
+    .. literalinclude:: ../tests/Functional/Fixtures/varnish-3/user_context.vcl
         :language: varnish3
-        :linenos:
+        :lines: 12,13,15
 
 .. _`builtin VCL`: https://www.varnish-cache.org/trac/browser/bin/varnishd/builtin.vcl?rev=4.0
 .. _`default VCL`: https://www.varnish-cache.org/trac/browser/bin/varnishd/default.vcl?rev=3.0

tests/Functional/Fixtures/varnish-3/ban.vcl renamed to resources/config/varnish-3/fos_ban.vcl

@@ -1,4 +1,13 @@
-sub vcl_recv {
+/*
+ * This file is part of the FOSHttpCache package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+sub fos_ban_recv {
 
     if (req.request == "BAN") {
         if (!client.ip ~ invalidators) {
@@ -22,20 +31,22 @@ sub vcl_recv {
     }
 }
 
-sub vcl_fetch {
+sub fos_ban_fetch {
 
     # Set ban-lurker friendly custom headers
     set beresp.http.X-Url = req.url;
     set beresp.http.X-Host = req.http.host;
 }
 
-sub vcl_deliver {
+sub fos_ban_deliver {
 
     # Keep ban-lurker headers only if debugging is enabled
     if (!resp.http.X-Cache-Debug) {
         # Remove ban-lurker friendly custom headers when delivering to client
         unset resp.http.X-Url;
         unset resp.http.X-Host;
+
+        # Unset the tagged cache headers
         unset resp.http.X-Cache-Tags;
     }
 }

resources/config/varnish-3/fos_debug.vcl

@@ -0,0 +1,19 @@
+/*
+ * This file is part of the FOSHttpCache package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+sub fos_debug_deliver {
+    # Add extra headers if debugging is enabled
+    if (resp.http.X-Cache-Debug) {
+        if (obj.hits > 0) {
+            set resp.http.X-Cache = "HIT";
+        } else {
+            set resp.http.X-Cache = "MISS";
+        }
+    }
+}

tests/Functional/Fixtures/varnish-3/purge.vcl renamed to resources/config/varnish-3/fos_purge.vcl

@@ -1,4 +1,13 @@
-sub vcl_recv {
+/*
+ * This file is part of the FOSHttpCache package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+sub fos_purge_recv {
     if (req.request == "PURGE") {
         if (!client.ip ~ invalidators) {
             error 405 "Not allowed";
@@ -7,7 +16,7 @@ sub vcl_recv {
     }
 }
 
-sub vcl_hit {
+sub fos_purge_hit {
     if (req.request == "PURGE") {
         purge;
         error 204 "Purged";
@@ -16,7 +25,7 @@ sub vcl_hit {
 
 # The purge in vcl_miss is necessary to purge all variants in the cases where
 # you hit an object, but miss a particular variant.
-sub vcl_miss {
+sub fos_purge_miss {
     if (req.request == "PURGE") {
         purge;
         error 204 "Purged (Not in cache)";

resources/config/varnish-3/fos_refresh.vcl

@@ -0,0 +1,14 @@
+/*
+ * This file is part of the FOSHttpCache package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+sub fos_refresh_recv {
+    if (req.http.Cache-Control ~ "no-cache" && client.ip ~ invalidators) {
+        set req.hash_always_miss = true;
+    }
+}