Merge pull request #150 from FriendsOfSymfony/symfony-cache-purge-refresh

add support for purge and refresh with symfony HttpCache

Author: ddeboer

composer.json

@@ -23,7 +23,8 @@
     "require": {
         "php": ">=5.3.3",
         "guzzle/http": "3.*",
-        "symfony/event-dispatcher": "~2.3"
+        "symfony/event-dispatcher": "~2.3",
+        "symfony/options-resolver": "~2.3"
     },
     "require-dev": {
         "guzzle/plugin-mock": "*",

doc/proxy-clients.rst

@@ -82,12 +82,15 @@ requests.
 Supported invalidation methods
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-======== ======= ======= =======
-Client   Purge   Refresh Ban
-======== ======= ======= =======
-Varnish  ✓       ✓       ✓
-Nginx    ✓       ✓
-======== ======= ======= =======
+============= ======= ======= =======
+Client        Purge   Refresh Ban
+============= ======= ======= =======
+Varnish       ✓       ✓       ✓
+Nginx         ✓       ✓
+Symfony Cache ✓       ✓
+============= ======= ======= =======
+
+.. _proxy-client purge:
 
 Purge
 ~~~~~
@@ -116,6 +119,8 @@ send any headers that you vary on, such as ``Accept``.
 
 .. include:: includes/custom-headers.rst
 
+.. _proxy-client refresh:
+
 Refresh
 ~~~~~~~
 

doc/symfony-cache-configuration.rst

@@ -17,12 +17,10 @@ concept is to use event subscribers on the HttpCache class.
 
 .. warning::
 
-    Symfony HttpCache support is currently limited to following features:
+    Symfony HttpCache does not currently provide support for banning.
 
-    * User context
-
-Extending the right HttpCache
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Extending the Correct HttpCache Class
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Instead of extending ``Symfony\Component\HttpKernel\HttpCache\HttpCache``, your
 ``AppCache`` should extend ``FOS\HttpCache\SymfonyCache\EventDispatchingHttpCache``.
@@ -59,6 +57,60 @@ subscribers there. A simple cache will look like this::
         }
     }
 
+Purge
+~~~~~
+
+To support :ref:`cache purging <proxy-client purge>`, register the
+``PurgeSubscriber``. If the default settings are right for you, you don't
+need to do anything more.
+
+Purging is only allowed from the same machine by default. To purge data from
+other hosts, provide the IPs of the machines allowed to purge, or provide a
+RequestMatcher that checks for an Authorization header or similar. *Only set
+one of purge_client_ips or purge_client_matcher*.
+
+* **purge_client_ips**: String with IP or array of IPs that are allowed to
+  purge the cache.
+
+  **default**: ``127.0.0.1``
+
+* **purge_client_matcher**: RequestMatcher that only matches requests that are
+  allowed to purge.
+
+  **default**: ``null``
+
+* **purge_method**: HTTP Method used with purge requests.
+
+  **default**: ``PURGE``
+
+Refresh
+~~~~~~~
+
+To support :ref:`cache refresh <proxy-client refresh>`, register the
+``RefreshSubscriber``. You can pass the constructor an option to specify
+what clients are allowed to refresh cache entries. Refreshing is only allowed
+from the same machine by default. To refresh from other hosts, provide the
+IPs of the machines allowed to refresh, or provide a RequestMatcher that
+checks for an Authorization header or similar. *Only set one of
+refresh_client_ips or refresh_client_matcher*.
+
+The refresh subscriber needs to access the ``HttpCache::fetch`` method which
+is protected on the base HttpCache class. The ``EventDispatchingHttpCache``
+exposes the method as public, but if you implement your own kernel, you need
+to overwrite the method to make it public.
+
+* **refresh_client_ips**: String with IP or array of IPs that are allowed to
+  refresh the cache.
+
+  **default**: ``127.0.0.1``
+
+* **refresh_client_matcher**: RequestMatcher that only matches requests that are
+  allowed to refresh.
+
+  **default**: ``null``
+
+.. _symfony-cache user context:
+
 User Context
 ~~~~~~~~~~~~
 
@@ -102,8 +154,8 @@ constructor:
     Session IDs are indeed used as keys to cache the generated use context hash.
 
     Wrong session name will lead to unexpected results such as having the same
-    user context hash for every users,
-    or not having it cached at all (painful for performance.
+    user context hash for every users, or not having it cached at all, which
+    hurts performance.
 
 Cleaning the Cookie Header
 ^^^^^^^^^^^^^^^^^^^^^^^^^^

doc/user-context.rst

@@ -45,7 +45,7 @@ Proxy Client Configuration
 
 Currently, user context caching is only supported by Varnish and by the Symfony
 HttpCache. See the :ref:`Varnish Configuration <varnish user context>` or
-:doc:`Symfony HttpCache Configuration <symfony-cache-configuration>`.
+:ref:`Symfony HttpCache Configuration <symfony-cache user context>`.
 
 Calculating the User Context Hash
 ---------------------------------

src/SymfonyCache/AccessControlledSubscriber.php

@@ -0,0 +1,73 @@
+<?php
+
+/*
+ * 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.
+ */
+
+namespace FOS\HttpCache\SymfonyCache;
+
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcher;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\Exception\BadRequestHttpException;
+use Symfony\Component\HttpKernel\HttpKernelInterface;
+
+/**
+ * Base class for handlers for the symfony built-in HttpCache that need access
+ * control on requests.
+ *
+ * @author David Buchmann <[email protected]>
+ *
+ * {@inheritdoc}
+ */
+abstract class AccessControlledSubscriber implements EventSubscriberInterface
+{
+    /**
+     * @var RequestMatcher
+     */
+    private $requestMatcher;
+
+    /**
+     * Initializes this subscriber with either a request matcher or an IP or
+     * list of IPs.
+     *
+     * Only one of request matcher or IPs may be a non-null value. If you use a
+     * RequestMatcher, configure your IPs into it.
+     *
+     * If neither parameter is set, the filter is IP 127.0.0.1
+     *
+     * @param RequestMatcher|null  $requestMatcher Request matcher configured to only match allowed requests.
+     * @param string|string[]|null $ips            IP or list of IPs that are allowed to send requests.
+     *
+     * @throws \InvalidArgumentException If both $requestMatcher and $ips are set.
+     */
+    public function __construct(RequestMatcher $requestMatcher = null, $ips = null)
+    {
+        if ($requestMatcher && $ips) {
+            throw new \InvalidArgumentException('You may not set both a request matcher and an IP.');
+        }
+        if (!$requestMatcher) {
+            $requestMatcher = new RequestMatcher(null, null, null, $ips ?: '127.0.0.1');
+        }
+
+        $this->requestMatcher = $requestMatcher;
+    }
+
+    /**
+     * Check whether the request is allowed.
+     *
+     * @param Request $request The request to check.
+     *
+     * @return boolean Whether access is granted.
+     */
+    protected function isRequestAllowed(Request $request)
+    {
+        return $this->requestMatcher->matches($request);
+    }
+}

src/SymfonyCache/EventDispatchingHttpCache.php

@@ -78,4 +78,32 @@ public function handle(Request $request, $type = HttpKernelInterface::MASTER_REQ
 
         return parent::handle($request, $type, $catch);
     }
+
+    /**
+     * Made public to allow event subscribers to do refresh operations.
+     *
+     * {@inheritDoc}
+     */
+    public function fetch(Request $request, $catch = false)
+    {
+        return parent::fetch($request, $catch);
+    }
+
+    /**
+     * {@inheritDoc}
+     *
+     * Adding the Events::PRE_INVALIDATE event.
+     */
+    protected function invalidate(Request $request, $catch = false)
+    {
+        if ($this->getEventDispatcher()->hasListeners(Events::PRE_INVALIDATE)) {
+            $event = new CacheEvent($this, $request);
+            $this->getEventDispatcher()->dispatch(Events::PRE_INVALIDATE, $event);
+            if ($event->getResponse()) {
+                return $event->getResponse();
+            }
+        }
+
+        return parent::invalidate($request, $catch);
+    }
 }

src/SymfonyCache/Events.php

@@ -17,4 +17,5 @@
 final class Events
 {
     const PRE_HANDLE = 'fos_http_cache.pre_handle';
+    const PRE_INVALIDATE = 'fos_http_cache.pre_invalidate';
 }

src/SymfonyCache/PurgeSubscriber.php

@@ -0,0 +1,103 @@
+<?php
+
+/*
+ * 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.
+ */
+
+namespace FOS\HttpCache\SymfonyCache;
+
+use Symfony\Component\EventDispatcher\EventSubscriberInterface;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestMatcher;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\HttpKernel\HttpKernelInterface;
+use Symfony\Component\OptionsResolver\OptionsResolver;
+
+/**
+ * Purge handler for the symfony built-in HttpCache.
+ *
+ * @author David Buchmann <[email protected]>
+ *
+ * {@inheritdoc}
+ */
+class PurgeSubscriber extends AccessControlledSubscriber
+{
+    /**
+     * The options configured in the constructor argument or default values.
+     *
+     * @var array
+     */
+    private $options = array();
+
+    /**
+     * When creating this subscriber, you can configure a number of options.
+     *
+     * - purge_method:         HTTP method that identifies purge requests.
+     * - purge_client_matcher: RequestMatcher to identify valid purge clients.
+     * - purge_client_ips:     IP or array of IPs that are allowed to purge.
+     *
+     * Only set one of purge_client_ips and purge_client_matcher.
+     *
+     * @param array $options Options to overwrite the default options
+     *
+     * @throws \InvalidArgumentException if unknown keys are found in $options
+     */
+    public function __construct(array $options = array())
+    {
+        $resolver = new OptionsResolver();
+        $resolver->setDefined(array('purge_client_matcher', 'purge_client_ips', 'purge_method'));
+        $resolver->setDefaults(array(
+            'purge_client_matcher' => null,
+            'purge_client_ips' => null,
+            'purge_method' => 'PURGE',
+        ));
+
+        $this->options = $resolver->resolve($options);
+
+        parent::__construct($this->options['purge_client_matcher'], $this->options['purge_client_ips']);
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    public static function getSubscribedEvents()
+    {
+        return array(
+            Events::PRE_INVALIDATE => 'handlePurge',
+        );
+    }
+
+    /**
+     * Look at unsafe requests and handle purge requests.
+     *
+     * Prevents access when the request comes from a non-authorized client.
+     *
+     * @param CacheEvent $event
+     */
+    public function handlePurge(CacheEvent $event)
+    {
+        $request = $event->getRequest();
+        if ($this->options['purge_method'] !== $request->getMethod()) {
+            return;
+        }
+
+        if (!$this->isRequestAllowed($request)) {
+            $event->setResponse(new Response('', 400));
+
+            return;
+        }
+
+        $response = new Response();
+        if ($event->getKernel()->getStore()->purge($request->getUri())) {
+            $response->setStatusCode(200, 'Purged');
+        } else {
+            $response->setStatusCode(200, 'Not found');
+        }
+        $event->setResponse($response);
+    }
+}