Add Cloudflare support

simonrjones · dbu · commit 645cd97e7ca6 · 2022-01-12T13:54:32.000+01:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,6 +6,13 @@ See also the [GitHub releases page](https://github.com/FriendsOfSymfony/FOSHttpC
 2.12.0 (unreleased)
 -------------------
 
+### Cloudflare
+
+* Added Cloudflare ProxyClient Adapter with ClearCapable, PurgeCapable and
+  TagCapable. This allows to use FOSHttpCache to invalidate caches on
+  Cloudflare. See the "Proxy Client" section of the documentation for how to
+  configure the Cloudflare client.
+
 ### Varnish Cache
 
 * Added a `fos_user_context_hash` method to be called in `vcl_hash` when using the user context
diff --git a/doc/proxy-clients.rst b/doc/proxy-clients.rst
@@ -26,11 +26,13 @@ Varnish       ✓       ✓       ✓       ✓
 Fastly        ✓       ✓               ✓       ✓
 NGINX         ✓       ✓
 Symfony Cache ✓       ✓               ✓ (1)   ✓ (1)
+Cloudflare    ✓                       ✓ (2)   ✓
 Noop          ✓       ✓       ✓       ✓       ✓
 Multiplexer   ✓       ✓       ✓       ✓       ✓
 ============= ======= ======= ======= ======= =======
 
-(1): Only when using `Toflar Psr6Store`_.
+| (1): Only when using `Toflar Psr6Store`_.
+| (2): Only available with `Cloudflare Enterprise`_.
 
 If needed, you can also implement your own client for other needs. Have a look
 at the interfaces in namespace ``FOS\HttpCache\ProxyClient\Invalidation``.
@@ -90,7 +92,8 @@ Varnish Client
 ~~~~~~~~~~~~~~
 
 The Varnish client sends HTTP requests with the ``HttpDispatcher``. Create the
-dispatcher as explained above and pass it to the Varnish client::
+dispatcher as explained :ref:`above <HTTP client configuration>` and pass it to
+the Varnish client::
 
     use FOS\HttpCache\ProxyClient\Varnish;
 
@@ -163,11 +166,12 @@ Fastly Client
 ~~~~~~~~~~~~~~
 
 The Fastly client sends HTTP requests with the ``HttpDispatcher``. Create the
-dispatcher as explained above and pass it to the Fastly client::
+dispatcher as explained :ref:`above <HTTP client configuration>` and pass it to
+the Fastly client::
 
     use FOS\HttpCache\ProxyClient\Fastly;
 
-    $varnish = new Fastly($httpDispatcher);
+    $fastly = new Fastly($httpDispatcher);
 
 .. note::
 
@@ -195,13 +199,14 @@ A full example could look like this::
     ];
     $requestFactory = new MyRequestFactory();
 
-    $varnish = new Fastly($httpDispatcher, $options, $requestFactory);
+    $fastly = new Fastly($httpDispatcher, $options, $requestFactory);
 
 NGINX Client
 ~~~~~~~~~~~~
 
 The NGINX client sends HTTP requests with the ``HttpDispatcher``. Create the
-dispatcher as explained above and pass it to the NGINX client::
+dispatcher as explained :ref:`above <HTTP client configuration>` and pass it to
+the NGINX client::
 
     use FOS\HttpCache\ProxyClient\Nginx;
 
@@ -224,7 +229,8 @@ Symfony Client
 ~~~~~~~~~~~~~~
 
 The Symfony client sends HTTP requests with the ``HttpDispatcher``. Create the
-dispatcher as explained above and pass it to the Symfony client::
+dispatcher as explained :ref:`above <HTTP client configuration>` and pass it to
+the Symfony client::
 
     use FOS\HttpCache\ProxyClient\Symfony;
 
@@ -296,6 +302,74 @@ And adapt your bootstrapping code to use the cache kernel::
     $response = $cacheKernel->handle($request);
     ...
 
+Cloudflare Client
+~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    Cloudflare does not cache HTML pages by default. To cache them, you need to
+    enable `custom caching with page rules`_ in the Cloudflare administration
+    interface.
+
+    The Cloudflare client does invalidation requests with the `Cloudflare Purge API`_.
+
+The `Cloudflare`_ client sends HTTP requests with the ``HttpDispatcher``.
+Create the dispatcher as explained :ref:`above <HTTP client configuration>`.
+Set the `server` list to the Cloudflare API `['https://api.cloudflare.com']`.
+Do not specify a base URI. The Cloudflare client does not work with base URIs,
+you need to always specify the full URL including domain name.
+
+Then create the Cloudflare client with the dispatcher. You also need to pass
+the following options:
+
+* ``authentication_token``: User API token for authentication against
+  Cloudflare APIs, requires `Zone.Cache` Purge permissions.
+* ``zone_identifier``: Identifier for the Cloudflare zone you want to purge the
+  cache for (see below how to obtain the identifier for your domain).
+
+A full example could look like this::
+
+    use FOS\HttpCache\CacheInvalidator;
+    use FOS\HttpCache\ProxyClient\Cloudflare;
+    use FOS\HttpCache\ProxyClient\HttpDispatcher;
+
+    $options = [
+        'authentication_token' => '<user-authentication-token>',
+        'zone_identifier' => '<my-zone-identifier>',
+    ];
+
+    $httpDispatcher = new HttpDispatcher(['https://api.cloudflare.com']);
+    $cloudflare = new Cloudflare($httpDispatcher, $options);
+    $cacheInvalidator = new CacheInvalidator($cloudflare);
+
+When purging the cache by URL, see the `Cloudflare Purge by URL`_ docs for
+information about how Cloudflare purges by URL and what headers you can
+pass to a :doc:`invalidatePath() <cache-invalidator>` request to clear the
+cache correctly.
+
+You need to always specify the domain to invalidate (the base URI mechanism of
+the HttpDispatcher is not available for Cloudflare)::
+
+    $cacheInvalidator->invalidatePath('https://example.com/path')->flush();
+
+.. note::
+
+    Cloudflare supports different cache purge methods depending on your account.
+    All Cloudflare accounts support purging the cache by URL and clearing all
+    cache items. You need a `Cloudflare Enterprise`_ account to purge by cache
+    tags.
+
+Zone identifier
+^^^^^^^^^^^^^^^
+To find the zone identifier for your domain request this from the API::
+
+    curl -X GET "https://api.cloudflare.com/client/v4/zones?name={DOMAIN.COM}" \
+    -H "Authorization: Bearer {API TOKEN}" \
+    -H "Content-Type:application/json"
+
+The zone identifier is returned in the ``id`` field of the results and is a
+32-character hexadecimal string.
+
 Noop Client
 ~~~~~~~~~~~
 
@@ -379,3 +453,8 @@ requests.
 .. _message factory and URI factory: http://php-http.readthedocs.io/en/latest/message/message-factory.html
 .. _Toflar Psr6Store: https://github.com/Toflar/psr6-symfony-http-cache-store
 .. _Fastly Purge API: https://docs.fastly.com/api/purge
+.. _Cloudflare: https://developers.cloudflare.com/cache/
+.. _custom caching with page rules: https://support.cloudflare.com/hc/en-us/articles/360021023712-Best-Practices-Speed-up-your-Site-with-Custom-Caching-via-Cloudflare-Page-Rules
+.. _Cloudflare Purge API: https://api.cloudflare.com/#zone-purge-all-files
+.. _Cloudflare Enterprise: https://developers.cloudflare.com/cache/how-to/purge-cache#cache-tags-enterprise-only
+.. _Cloudflare Purge by URL: https://developers.cloudflare.com/cache/how-to/purge-cache#purge-by-single-file-by-url
diff --git a/doc/spelling_word_list.txt b/doc/spelling_word_list.txt
@@ -32,3 +32,4 @@ inline
 Noop
 xkey
 ykey
+Cloudflare
diff --git a/src/ProxyClient/Cloudflare.php b/src/ProxyClient/Cloudflare.php
@@ -0,0 +1,180 @@
+<?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\ProxyClient;
+
+use FOS\HttpCache\ProxyClient\Invalidation\ClearCapable;
+use FOS\HttpCache\ProxyClient\Invalidation\PurgeCapable;
+use FOS\HttpCache\ProxyClient\Invalidation\TagCapable;
+use Http\Message\RequestFactory;
+
+/**
+ * Cloudflare HTTP cache invalidator.
+ *
+ * Additional constructor options:
+ * - zone_identifier       Identifier for your Cloudflare zone you want to purge the cache for
+ * - authentication_token  API authorization token, requires Zone.Cache Purge permissions
+ *
+ * @author Simon Jones <simon@studio24.net>
+ */
+class Cloudflare extends HttpProxyClient implements ClearCapable, PurgeCapable, TagCapable
+{
+    /**
+     * @see https://api.cloudflare.com/#getting-started-endpoints
+     */
+    private const API_ENDPOINT = '/client/v4';
+
+    /**
+     * Batch URL purge limit.
+     *
+     * @see https://api.cloudflare.com/#zone-purge-files-by-url
+     */
+    private const URL_BATCH_PURGE_LIMIT = 30;
+
+    /**
+     * Array of data to send to Cloudflare for purge by URLs request.
+     *
+     * To reduce the number of requests to cloudflare, we buffer the URLs.
+     * During flush, we build requests with batches of URL_BATCH_PURGE_LIMIT.
+     *
+     * @var array<string|array{url: string, headers: string[]}>
+     */
+    private $purgeByUrlsData = [];
+
+    public function __construct(
+        Dispatcher $httpDispatcher,
+        array $options = [],
+        RequestFactory $messageFactory = null
+    ) {
+        if (!function_exists('json_encode')) {
+            throw new \Exception('ext-json is required for cloudflare invalidation');
+        }
+
+        parent::__construct($httpDispatcher, $options, $messageFactory);
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * Tag invalidation only available with Cloudflare enterprise account
+     *
+     * @see https://api.cloudflare.com/#zone-purge-files-by-cache-tags,-host-or-prefix
+     */
+    public function invalidateTags(array $tags)
+    {
+        $this->queueRequest(
+            'POST',
+            sprintf(self::API_ENDPOINT.'/zones/%s/purge_cache', $this->options['zone_identifier']),
+            [],
+            false,
+            $this->json_encode(['tags' => $tags])
+        );
+
+        return $this;
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see https://api.cloudflare.com/#zone-purge-files-by-url
+     * @see https://developers.cloudflare.com/cache/how-to/purge-cache#purge-by-single-file-by-url For details on headers you can pass to clear the cache correctly
+     */
+    public function purge($url, array $headers = [])
+    {
+        if (!empty($headers)) {
+            $this->purgeByUrlsData[] = [
+                'url' => $url,
+                'headers' => $headers,
+            ];
+        } else {
+            $this->purgeByUrlsData[] = $url;
+        }
+
+        return $this;
+    }
+
+    /**
+     * {@inheritdoc}
+     *
+     * @see https://api.cloudflare.com/#zone-purge-all-files
+     */
+    public function clear()
+    {
+        $this->queueRequest(
+            'POST',
+            sprintf(self::API_ENDPOINT.'/zones/%s/purge_cache', $this->options['zone_identifier']),
+            ['Accept' => 'application/json'],
+            false,
+            $this->json_encode(['purge_everything' => true])
+        );
+
+        return $this;
+    }
+
+    /**
+     * {@inheritdoc} Queue requests for purge by URLs
+     */
+    public function flush()
+    {
+        // Queue requests for purge by URL
+        foreach (\array_chunk($this->purgeByUrlsData, self::URL_BATCH_PURGE_LIMIT) as $urlChunk) {
+            $this->queueRequest(
+                'POST',
+                sprintf(self::API_ENDPOINT.'/zones/%s/purge_cache', $this->options['zone_identifier']),
+                [],
+                false,
+                $this->json_encode(['files' => $urlChunk])
+            );
+        }
+        $this->purgeByUrlsData = [];
+
+        return parent::flush();
+    }
+
+    /**
+     * {@inheritdoc} Always provides authentication token
+     */
+    protected function queueRequest($method, $url, array $headers, $validateHost = true, $body = null)
+    {
+        parent::queueRequest(
+            $method,
+            $url,
+            $headers + ['Authorization' => 'Bearer '.$this->options['authentication_token']],
+            $validateHost,
+            $body
+        );
+    }
+
+    /**
+     * {@inheritdoc}
+     */
+    protected function configureOptions()
+    {
+        $resolver = parent::configureOptions();
+
+        $resolver->setRequired([
+            'authentication_token',
+            'zone_identifier',
+        ]);
+
+        return $resolver;
+    }
+
+    private function json_encode(array $data): string
+    {
+        $json = json_encode($data, JSON_UNESCAPED_SLASHES);
+        if (false === $json) {
+            throw new \InvalidArgumentException(sprintf('Cannot encode "$data": %s', json_last_error_msg()));
+        }
+
+        return $json;
+    }
+}
diff --git a/src/ProxyClient/Fastly.php b/src/ProxyClient/Fastly.php
@@ -15,6 +15,7 @@
 use FOS\HttpCache\ProxyClient\Invalidation\PurgeCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\RefreshCapable;
 use FOS\HttpCache\ProxyClient\Invalidation\TagCapable;
+use Http\Message\RequestFactory;
 
 /**
  * Fastly HTTP cache invalidator.
@@ -44,6 +45,18 @@ class Fastly extends HttpProxyClient implements ClearCapable, PurgeCapable, Refr
      */
     private const API_ENDPOINT = 'https://api.fastly.com';
 
+    public function __construct(
+        Dispatcher $httpDispatcher,
+        array $options = [],
+        RequestFactory $messageFactory = null
+    ) {
+        if (!function_exists('json_encode')) {
+            throw new \Exception('ext-json is required for fastly invalidation');
+        }
+
+        parent::__construct($httpDispatcher, $options, $messageFactory);
+    }
+
     /**
      * {@inheritdoc}
      *
diff --git a/tests/Unit/ProxyClient/CloudflareTest.php b/tests/Unit/ProxyClient/CloudflareTest.php

-Original file line number
+Diff line change
 Noop
 xkey
 ykey
 +Cloudflare