improve caching of the user context hash lookup in Varnish

CHANGELOG.md

@@ -3,6 +3,17 @@ Changelog
 
 See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpCache/releases).
 
+2.12.0 (unreleased)
+-------------------
+
+### Varnish Cache
+
+* Added a `fos_user_context_hash` method to be called in `vcl_hash` when using the user context
+  hash mechanism. This can avoid performance problems Varnish can run into when the hash `Vary`s on
+  the basic authentication or session cookie.
+  If you use the user context, read the updated documentation and call `fos_user_context_hash` in
+  your `vcl_hash` function.
+
 2.11.0
 ------
 

doc/varnish-configuration.rst

@@ -295,6 +295,10 @@ To enable this feature, add the following to ``your_varnish.vcl``:
             call fos_user_context_recv;
         }
 
+        sub vcl_hash {
+            call fos_user_context_hash;
+        }
+
         sub vcl_backend_response {
             call fos_user_context_backend_response;
         }
@@ -312,6 +316,10 @@ To enable this feature, add the following to ``your_varnish.vcl``:
             call fos_user_context_recv;
         }
 
+        sub vcl_hash {
+            call fos_user_context_hash;
+        }
+
         sub vcl_fetch {
             call fos_user_context_fetch;
         }
@@ -344,6 +352,13 @@ request with :ref:`a proper user hash <return context hash>`.
     set the ``req.url`` to a fixed URL. Otherwise Varnish would cache every
     hash lookup separately.
 
+    The ``fos_user_context_hash`` should be used to separate the cache of the
+    hash lookup. If you don't do that, Varnish can run into performance issues
+    because the user hash lookup creates a `large number of variants`_. If your
+    hash is taking into account other headers than ``Authorization`` and
+    ``Cookie``, create your own ``vcl_hash`` function that adds all those
+    headers to ``hash_data`` for user context hash lookup requests.
+
     However, if you have a :ref:`paywall scenario <paywall_usage>`, you need to
     leave the original URL unchanged. For that case, you would need to write
     your own VCL.
@@ -468,5 +483,6 @@ To enable this feature, add the following to ``your_varnish.vcl``:
 .. _ykey documentation: https://docs.varnish-software.com/varnish-cache-plus/vmods/ykey/
 .. _Cache Invalidation chapter of the Varnish documentation: http://book.varnish-software.com/4.0/chapters/Cache_Invalidation.html#hashtwo-xkey-varnish-software-implementation-of-surrogate-keys
 .. _installing xkey: https://github.com/varnish/varnish-modules#installation
+.. _large number of variants: https://github.com/varnishcache/varnish-cache/pull/3520
 .. _`builtin VCL`: https://github.com/varnishcache/varnish-cache/blob/5.0/bin/varnishd/builtin.vcl
 .. _`default VCL`: https://github.com/varnishcache/varnish-cache/blob/3.0/bin/varnishd/default.vcl

resources/config/varnish-3/fos_user_context.vcl

@@ -43,6 +43,10 @@ sub fos_user_context_recv {
 
         # Force the lookup, the backend must tell not to cache or vary on all
         # headers that are used to build the hash.
+        #
+        # To avoid massive performance issues when caching the hash lookup request, see
+        # fos_user_context_hash
+
         return (lookup);
     }
 
@@ -67,6 +71,21 @@ sub fos_user_context_recv {
     }
 }
 
+/**
+ * When caching the hash lookup request with a session or basic auth, we should include that
+ * information in the hash.
+ *
+ * If we would only rely on Varnish keeping the variants of the response apart with the Vary
+ * header, Varnish has to lookup the right variant. With a large number of users, this is extremly
+ * inefficient as Varnish does not optimize Variant search and we get O(n) on the number of users.
+ */
+sub fos_user_context_hash {
+    if (req.http.accept == "application/vnd.fos.user-context-hash") {
+        hash_data(req.http.Cookie);
+        hash_data(req.http.Autorization);
+    }
+}
+
 sub fos_user_context_fetch {
     if (req.restarts == 0
         && req.http.accept ~ "application/vnd.fos.user-context-hash"

resources/config/varnish-3/fos_user_context_url.vcl

@@ -7,6 +7,9 @@
  * file that was distributed with this source code.
  */
 
+/**
+ * This function is in a separate file so that you can easily adjust the lookup URL to your needs.
+ */
 sub user_context_hash_url {
 	set req.url = "/_fos_user_context_hash";
 }

resources/config/varnish/fos_user_context.vcl

@@ -43,6 +43,10 @@ sub fos_user_context_recv {
 
         # Force the lookup, the backend must tell not to cache or vary on all
         # headers that are used to build the hash.
+        #
+        # To avoid massive performance issues when caching the hash lookup request, see
+        # fos_user_context_hash
+
         return (hash);
     }
 
@@ -67,6 +71,21 @@ sub fos_user_context_recv {
     }
 }
 
+/**
+ * When caching the hash lookup request with a session or basic auth, we should include that
+ * information in the hash.
+ *
+ * If we would only rely on Varnish keeping the variants of the response apart with the Vary
+ * header, Varnish has to lookup the right variant. With a large number of users, this is extremly
+ * inefficient as Varnish does not optimize Variant search and we get O(n) on the number of users.
+ */
+sub fos_user_context_hash {
+    if (req.http.accept == "application/vnd.fos.user-context-hash") {
+        hash_data(req.http.Cookie);
+        hash_data(req.http.Autorization);
+    }
+}
+
 sub fos_user_context_backend_response {
     if (bereq.http.accept ~ "application/vnd.fos.user-context-hash"
         && beresp.status >= 500

resources/config/varnish/fos_user_context_url.vcl

@@ -7,6 +7,9 @@
  * file that was distributed with this source code.
  */
 
+/**
+ * This function is in a separate file so that you can easily adjust the lookup URL to your needs.
+ */
 sub user_context_hash_url {
 	set req.url = "/_fos_user_context_hash";
 }

tests/Functional/Fixtures/varnish-3/user_context.vcl

@@ -5,11 +5,15 @@ sub vcl_recv {
     call fos_user_context_recv;
 }
 
+sub vcl_hash {
+    call fos_user_context_hash;
+}
+
 sub vcl_fetch {
     call fos_user_context_fetch;
 }
 
 sub vcl_deliver {
     call fos_debug_deliver;
     call fos_user_context_deliver;
-}
+}

tests/Functional/Fixtures/varnish/user_context.vcl

@@ -5,6 +5,10 @@ sub vcl_recv {
     call fos_user_context_recv;
 }
 
+sub vcl_hash {
+    call fos_user_context_hash;
+}
+
 sub vcl_backend_response {
     call fos_user_context_backend_response;
 }