improve caching of the user context hash lookup in Varnish

Thanks to Bastian Jaillot (@bastnic) for reporting the performance analysis and proposing this solution. Further details can be found at #496

Author: dbu

CHANGELOG.md

@@ -3,6 +3,17 @@ Changelog
 
 See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpCache/releases).
 
+2.10.1
+------
+
+### 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.10.0
 ------
 

doc/varnish-configuration.rst

@@ -297,6 +297,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;
  }
@@ -314,6 +318,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;
  }
@@ -346,6 +354,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.
@@ -470,5 +485,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;
 }