Merge pull request #93 from sensiolabs/issue-10-cache

split the HTTP cache chapter

Author: weaverryan

cache/cache_invalidation.rst

@@ -0,0 +1,104 @@
+.. index::
+   single: Cache; Invalidation
+
+.. _http-cache-invalidation:
+
+Cache Invalidation
+~~~~~~~~~~~~~~~~~~
+
+    "There are only two hard things in Computer Science: cache invalidation
+    and naming things." -- Phil Karlton
+
+Once an URL is cached by a gateway cache, the cache will not ask the
+application for that content anymore. This allows the cache to provide fast
+responses and reduces the load on your application. However, you risk
+delivering outdated content. A way out of this dilemma is to use long
+cache lifetimes, but to actively notify the gateway cache when content
+changes. Reverse proxies usually provide a channel to receive such
+notifications, typically through special HTTP requests.
+
+.. caution::
+
+    While cache invalidation is powerful, avoid it when possible. If you fail
+    to invalidate something, outdated caches will be served for a potentially
+    long time. Instead, use short cache lifetimes or use the validation model,
+    and adjust your controllers to perform efficient validation checks as
+    explained in :ref:`optimizing-cache-validation`.
+
+    Furthermore, since invalidation is a topic specific to each type of reverse
+    proxy, using this concept will tie you to a specific reverse proxy or need
+    additional efforts to support different proxies.
+
+Sometimes, however, you need that extra performance you can get when
+explicitly invalidating. For invalidation, your application needs to detect
+when content changes and tell the cache to remove the URLs which contain
+that data from its cache.
+
+.. tip::
+
+    If you want to use cache invalidation, have a look at the
+    `FOSHttpCacheBundle`_. This bundle provides services to help with various
+    cache invalidation concepts and also documents the configuration for a
+    couple of common caching proxies.
+
+If one content corresponds to one URL, the ``PURGE`` model works well.
+You send a request to the cache proxy with the HTTP method ``PURGE`` (using
+the word "PURGE" is a convention, technically this can be any string) instead
+of ``GET`` and make the cache proxy detect this and remove the data from the
+cache instead of going to the application to get a response.
+
+Here is how you can configure the Symfony reverse proxy to support the
+``PURGE`` HTTP method::
+
+    // app/AppCache.php
+
+    use Symfony\Bundle\FrameworkBundle\HttpCache\HttpCache;
+    use Symfony\Component\HttpFoundation\Request;
+    use Symfony\Component\HttpFoundation\Response;
+    // ...
+
+    class AppCache extends HttpCache
+    {
+        protected function invalidate(Request $request, $catch = false)
+        {
+            if ('PURGE' !== $request->getMethod()) {
+                return parent::invalidate($request, $catch);
+            }
+
+            if ('127.0.0.1' !== $request->getClientIp()) {
+                return new Response(
+                    'Invalid HTTP method',
+                    Response::HTTP_BAD_REQUEST
+                );
+            }
+
+            $response = new Response();
+            if ($this->getStore()->purge($request->getUri())) {
+                $response->setStatusCode(200, 'Purged');
+            } else {
+                $response->setStatusCode(404, 'Not found');
+            }
+
+            return $response;
+        }
+    }
+
+.. caution::
+
+    You must protect the ``PURGE`` HTTP method somehow to avoid random people
+    purging your cached data.
+
+**Purge** instructs the cache to drop a resource in *all its variants*
+(according to the ``Vary`` header, see above). An alternative to purging is
+**refreshing** a content. Refreshing means that the caching proxy is
+instructed to discard its local cache and fetch the content again. This way,
+the new content is already available in the cache. The drawback of refreshing
+is that variants are not invalidated.
+
+In many applications, the same content bit is used on various pages with
+different URLs. More flexible concepts exist for those cases:
+
+* **Banning** invalidates responses matching regular expressions on the
+  URL or other criteria;
+* **Cache tagging** lets you add a tag for each content used in a response
+  so that you can invalidate all URLs containing a certain content.

cache/cache_vary.rst

@@ -0,0 +1,45 @@
+.. index::
+   single: Cache; Vary
+   single: HTTP headers; Vary
+
+Varying the Response for HTTP Cache
+===================================
+
+So far, it's been assumed that each URI has exactly one representation of the
+target resource. By default, HTTP caching is done by using the URI of the
+resource as the cache key. If two people request the same URI of a cacheable
+resource, the second person will receive the cached version.
+
+Sometimes this isn't enough and different versions of the same URI need to
+be cached based on one or more request header values. For instance, if you
+compress pages when the client supports it, any given URI has two representations:
+one when the client supports compression, and one when it does not. This
+determination is done by the value of the ``Accept-Encoding`` request header.
+
+In this case, you need the cache to store both a compressed and uncompressed
+version of the response for the particular URI and return them based on the
+request's ``Accept-Encoding`` value. This is done by using the ``Vary`` response
+header, which is a comma-separated list of different headers whose values
+trigger a different representation of the requested resource:
+
+.. code-block:: text
+
+    Vary: Accept-Encoding, User-Agent
+
+.. tip::
+
+    This particular ``Vary`` header would cache different versions of each
+    resource based on the URI and the value of the ``Accept-Encoding`` and
+    ``User-Agent`` request header.
+
+The ``Response`` object offers a clean interface for managing the ``Vary``
+header::
+
+    // set one vary header
+    $response->setVary('Accept-Encoding');
+
+    // set multiple vary headers
+    $response->setVary(array('Accept-Encoding', 'User-Agent'));
+
+The ``setVary()`` method takes a header name or an array of header names for
+which the response varies.