Merge pull request #207 from FriendsOfSymfony/etag

add support for a simple etag

Author: ddeboer

CHANGELOG.md

@@ -13,6 +13,7 @@ Changelog
 
   **deprecated** `CacheManager::tagResponse` in favor of `TagHandler::addTags`
 * **2015-05-08** Added configuration option for custom proxy client (#208)
+* Added support for a simple Etag header in the header configuration (#207)
 
 1.2.0
 -----

DependencyInjection/Configuration.php

@@ -206,6 +206,10 @@ private function addCacheControlSection(ArrayNodeDefinition $rootNode)
                             ->scalarNode('stale_while_revalidate')->end()
                         ->end()
                     ->end()
+                    ->scalarNode('etag')
+                        ->defaultValue(false)
+                        ->info('Set a simple ETag which is just the md5 hash of the response body')
+                    ->end()
                     ->scalarNode('last_modified')
                         ->validate()
                             ->ifTrue(function ($v) {

EventListener/CacheControlSubscriber.php

@@ -130,6 +130,11 @@ public function onKernelResponse(FilterResponseEvent $event)
                 $response->setVary($options['vary'], $options['overwrite']);
             }
 
+            if (!empty($options['etag'])
+                && ($options['overwrite'] || null === $response->getEtag())
+            ) {
+                $response->setEtag(md5($response->getContent()));
+            }
             if (isset($options['last_modified'])
                 && ($options['overwrite'] || null === $response->getLastModified())
             ) {

Resources/doc/features/headers.rst

@@ -17,7 +17,7 @@ headers are added. You can force to overwrite the headers globally by setting
 ``cache_control.defaults.overwrite: true`` to true, or on a per rule basis with
 ``overwrite: true`` under ``headers``.
 
-This is an example configuration. For more, see the  
+This is an example configuration. For more, see the
 :doc:`/reference/configuration/headers` configuration reference.
 
 .. code-block:: yaml
@@ -34,7 +34,7 @@ This is an example configuration. For more, see the
                         host: ^login.example.com$
                     headers:
                         cache_control: { public: false, max_age: 0, s_maxage: 0 }
-                        last_modified: "-1 hour"
+                        etag: true
                         vary: [Accept-Encoding, Accept-Language]
 
                 # match all actions of a specific controller
@@ -51,7 +51,7 @@ This is an example configuration. For more, see the
                         path: ^/$
                     headers:
                         cache_control: { public: true, max_age: 64000, s_maxage: 64000 }
-                        last_modified: "-1 hour"
+                        etag: true
                         vary: [Accept-Encoding, Accept-Language]
 
                 # match everything to set defaults
@@ -61,7 +61,7 @@ This is an example configuration. For more, see the
                     headers:
                         overwrite: false
                         cache_control: { public: true, max_age: 15, s_maxage: 30 }
-                        last_modified: "-1 hour"
+                        etag: true
 
 .. _manually setting cache headers: http://symfony.com/doc/current/book/http_cache.html#the-cache-control-header
 .. _setting caching headers through annotations: http://symfony.com/doc/current/bundles/SensioFrameworkExtraBundle/annotations/cache.html

Resources/doc/reference/configuration/headers.rst

@@ -7,7 +7,7 @@ parameters described in the ``match`` section, the headers as defined under
 checked in the order specified, where the first match wins.
 
 A global setting and a per rule ``overwrite`` option allow to overwrite the
-cache headers even if they are already set.
+cache headers even if they are already set:
 
 .. code-block:: yaml
 
@@ -27,7 +27,7 @@ cache headers even if they are already set.
                             public: false
                             max_age: 0
                             s_maxage: 0
-                        last_modified: "-1 hour"
+                        etag: true
                         vary: [Accept-Encoding, Accept-Language]
 
                 # match all actions of a specific controller
@@ -50,7 +50,7 @@ cache headers even if they are already set.
                             public: true
                             max_age: 64000
                             s_maxage: 64000
-                        last_modified: "-1 hour"
+                        etag: true
                         vary: [Accept-Encoding, Accept-Language]
 
                 # match everything to set defaults
@@ -62,7 +62,7 @@ cache headers even if they are already set.
                             public: true
                             max_age: 15
                             s_maxage: 30
-                        last_modified: "-1 hour"
+                        etag: true
 
 ``rules``
 ---------
@@ -143,7 +143,7 @@ You can use the standard cache control directives:
 * ``s_maxage`` time in seconds for proxy caches (also public caches);
 * ``private`` true or false;
 * ``public`` true or false;
-* ``no_cache`` true or false (use exclusively to support HTTP 1.0);
+* ``no_cache`` true or false (use exclusively to support HTTP 1.0).
 
 .. code-block:: yaml
 
@@ -166,23 +166,24 @@ default. If you want it respected, add your own logic to ``vcl_fetch``.
 
 .. note::
 
-    The cache-control headers are described in detail in :rfc:`2616#section-14.9`.
+    The cache-control headers are described in detail in :rfc:`2616#section-14.9`
+    and further clarified in :rfc:`7234#section-5.2`.
 
 Extra Cache Control Directives
 """"""""""""""""""""""""""""""
 
 You can also set headers that Symfony considers non-standard, some coming from
-RFCs extending HTTP/1.1. The following options are supported:
+RFCs extending :rfc:`2616` HTTP/1.1. The following options are supported:
 
-* ``must_revalidate`` (:rfc:`2616#section-14.9`)
-* ``proxy_revalidate`` (:rfc:`2616#section-14.9`)
-* ``no_transform`` (:rfc:`2616#section-14.9`)
-* ``stale_if_error``: seconds (:rfc:`5861`)
-* ``stale_while_revalidate``: seconds (:rfc:`5861`)
+* ``must_revalidate`` (:rfc:`7234#section-5.2.2.1`)
+* ``proxy_revalidate`` (:rfc:`7234#section-5.2.2.7`)
+* ``no_transform`` (:rfc:`7234#section-5.2.2.4`)
+* ``stale_if_error``: seconds (:rfc:`5861#section-4`)
+* ``stale_while_revalidate``: seconds (:rfc:`5861#section-3`)
 
 The *stale* directives need a parameter specifying the time in seconds how long
 a  cache is allowed to continue serving stale content if needed. The other
-directives are flags that are included when set to true.
+directives are flags that are included when set to true:
 
 .. code-block:: yaml
 
@@ -200,13 +201,46 @@ directives are flags that are included when set to true.
                             proxy_revalidate: true
                             no_transform: true
 
+``etag``
+""""""""
+
+**type**: ``boolean``
+
+This enables a simplistic ETag calculated as md5 hash of the response body:
+
+.. code-block:: yaml
+
+    # app/config/config.yml
+    fos_http_cache:
+        cache_control:
+            rules:
+                -
+                    headers:
+                        etag: true
+
+.. tip::
+
+    This simplistic ETag handler will not help you to prevent unnecessary work
+    on your web server, but allows a caching proxy to use the ETag cache
+    validation method to preserve bandwidth. The presence of an ETag tells
+    clients that they can send a ``If-None-Match`` header with the ETag their
+    current version of the content has. If the caching proxy still has the same
+    ETag, it responds with a "304 Not Modified" status.
+
+    You can get additional performance if you write your own ETag handler that
+    can read an ETag from your content and decide very early in the request
+    whether the ETag changed or not. It can then terminate the request early
+    with an empty "304 Not Modified" response. This avoids rendering the whole
+    page. If the page depends on permissions, make sure to make the ETag differ
+    based on those permissions (e.g. by appending the :doc:`user context hash </features/user-context>`).
+
 ``last_modified``
 """""""""""""""""
 
 **type**: ``string``
 
 The input to the ``last_modified`` is used for the ``Last-Modified`` header.
-This value must be a valid input to ``DateTime``.
+This value must be a valid input to ``DateTime``:
 
 .. code-block:: yaml
 
@@ -218,20 +252,36 @@ This value must be a valid input to ``DateTime``.
                     headers:
                         last_modified: "-1 hour"
 
-.. hint::
+.. note::
 
     Setting an arbitrary last modified time allows clients to send
     ``If-Modified-Since`` requests. Varnish can handle these to serve data
     from the cache if it was not invalidated since the client requested it.
 
+    Note that the default system will generate an arbitrary last modified date.
+    You can get additional performance if you write your own last modified
+    handler that can compare this date with information about the content of
+    your page and decide early in the request whether anything changed. It can
+    then terminate the request early with an empty "304 Not Modified" response.
+    Using content meta data increases the probability for a 304 response and
+    avoids rendering the whole page.
+
+    See also :rfc:`7232#section-2.2.1` for further consideration on how to
+    generate the last modified date.
+
+.. note::
+
+    You may configure both ETag and last modified on the same response. See
+    :rfc:`7232#section-2.4` for more details.
+
 ``vary``
 """"""""
 
 **type**: ``string``
 
 You can set the `vary` option to an array that defines the contents of the
 `Vary` header when matching the request. This adds to existing Vary headers,
-keeping previously set Vary options.
+keeping previously set Vary options:
 
 .. code-block:: yaml
 

Resources/doc/spelling_word_list.txt

@@ -8,3 +8,4 @@ github
 subdomains
 yaml
 invalidator
+ETag

Tests/Resources/Fixtures/config/full.php

@@ -28,6 +28,7 @@
                         'stale_if_error' => 3,
                         'stale_while_revalidate' => 4,
                     ),
+                    'etag' => true,
                     'last_modified' => '-1 hour',
                     'reverse_proxy_ttl' => 42,
                     'vary' => array('Cookie', 'Authorization'),

Tests/Resources/Fixtures/config/full.xml

@@ -19,7 +19,7 @@
                     <additional-cacheable-status>100</additional-cacheable-status>
                     <additional-cacheable-status>500</additional-cacheable-status>
                 </match>
-                <headers last-modified="-1 hour" reverse-proxy-ttl="42">
+                <headers etag="true" last-modified="-1 hour" reverse-proxy-ttl="42">
                     <overwrite>false</overwrite>
                     <cache-control
                         max-age="1"

Tests/Resources/Fixtures/config/full.yml

@@ -31,6 +31,7 @@ fos_http_cache:
                         no_cache: false
                         stale_if_error: 3
                         stale_while_revalidate: 4
+                    etag: true
                     last_modified: -1 hour
                     reverse_proxy_ttl: 42
                     vary:

Tests/Unit/DependencyInjection/ConfigurationTest.php

@@ -77,6 +77,7 @@ public function testSupportsAllConfigFormats()
                                 'stale_if_error' => 3,
                                 'stale_while_revalidate' => 4,
                             ),
+                            'etag' => true,
                             'last_modified' => '-1 hour',
                             'reverse_proxy_ttl' => 42,
                             'vary' => array('Cookie', 'Authorization'),
@@ -232,6 +233,7 @@ public function testSplitOptions()
                         'reverse_proxy_ttl' => null,
                         'vary' => array('Cookie', 'Authorization'),
                         'overwrite' => 'default',
+                        'etag' => false,
                     ),
                 ),
             ),

Tests/Unit/EventListener/CacheControlSubscriberTest.php

@@ -128,6 +128,7 @@ public function testMergeHeaders()
             'vary' => array(
                 'Cookie',
             ),
+            'etag' => true,
             'last_modified' => '2014-10-10 GMT',
         );
         $subscriber = $this->getCacheControl($headers);
@@ -136,13 +137,15 @@ public function testMergeHeaders()
         $response->setCache(array('max_age' => 0));
         $response->headers->addCacheControlDirective('stale-if-error', 0);
         $response->setVary('Encoding');
+        $response->setEtag('foo');
         $response->setLastModified(new \DateTime('2013-09-09 GMT'));
 
         $subscriber->onKernelResponse($event);
         $newHeaders = $event->getResponse()->headers->all();
 
         $this->assertEquals('max-age=0, must-revalidate, no-transform, proxy-revalidate, public, s-maxage=300, stale-if-error=0, stale-while-revalidate=400', $newHeaders['cache-control'][0]);
         $this->assertEquals(array('Encoding', 'Cookie'), $newHeaders['vary']);
+        $this->assertEquals('"foo"', $newHeaders['etag'][0]);
         $this->assertEquals('Mon, 09 Sep 2013 00:00:00 GMT', $newHeaders['last-modified'][0]);
     }
 
@@ -165,6 +168,7 @@ public function testOverwriteHeaders()
             'vary' => array(
                 'Cookie',
             ),
+            'etag' => true,
             'last_modified' => '2014-10-10 GMT',
         );
         $subscriber = $this->getCacheControl($headers);
@@ -173,13 +177,15 @@ public function testOverwriteHeaders()
         $response->setCache(array('max_age' => 0));
         $response->headers->addCacheControlDirective('stale-if-error', 0);
         $response->setVary('Encoding');
+        $response->setEtag('foo');
         $response->setLastModified(new \DateTime('2013-09-09 GMT'));
 
         $subscriber->onKernelResponse($event);
         $newHeaders = $event->getResponse()->headers->all();
 
         $this->assertEquals('max-age=900, must-revalidate, no-transform, proxy-revalidate, public, s-maxage=300, stale-if-error=300, stale-while-revalidate=400', $newHeaders['cache-control'][0]);
         $this->assertEquals(array('Cookie'), $newHeaders['vary']);
+        $this->assertEquals('"'.md5('').'"', $response->getEtag());
         $this->assertEquals('Fri, 10 Oct 2014 00:00:00 GMT', $newHeaders['last-modified'][0]);
     }