LiteSpeed support

.travis.yml

@@ -60,7 +60,6 @@ install:
 before_script:
   # Install Varnish
   - |
-    set -e
     curl -L https://packagecloud.io/varnishcache/varnish${VARNISH_VERSION//./}/gpgkey | sudo apt-key add -
     curl -L "https://packagecloud.io/install/repositories/varnishcache/varnish${VARNISH_VERSION//./}/config_file.list?os=ubuntu&dist=trusty&source=script" | sudo tee -a /etc/apt/sources.list
     cat /etc/apt/sources.list
@@ -71,6 +70,8 @@ before_script:
   - if [ "$VARNISH_MODULES_VERSION" != "" ]; then sh ./tests/install-varnish-modules.sh; fi
   # Install NGINX
   - sh ./tests/install-nginx.sh
+  # Install OpenLiteSpeed
+  - sh ./tests/install-openlitespeed.sh
 
 script:
   - composer validate --strict --no-check-lock
@@ -87,3 +88,5 @@ after_failure:
   - sudo cat /var/log/apache2/error.log
   - sudo cat /var/log/apache2/access.log
   - sudo cat /var/log/apache2/other_vhosts_access.log
+  - for errorlog in '/usr/local/lsws/logs/error.log*'; do sudo cat $errorlog; done
+  - sudo cat /usr/local/lsws/logs/access.log

doc/cache-invalidator.rst

@@ -18,6 +18,8 @@ Create the cache invalidator by passing a proxy client as
     // or
     $client = new ProxyClient\Nginx(...);
     // or
+    $client = new ProxyClient\LiteSpeed(...);
+    // or
     $client = new ProxyClient\Symfony(...);
     // or, for local development
     $client = new ProxyClient\Noop();

doc/litespeed-configuration.rst

@@ -0,0 +1,153 @@
+.. _litespeed configuration:
+
+LiteSpeed Configuration
+-----------------------
+
+Below you will find detailed LiteSpeed configuration recommendations for the
+features provided by this library.
+
+Preamble
+~~~~~~~~
+
+First of all, let's get one thing straight here: You'll find a lot of documentation
+and noise around LiteSpeed cache on the Internet, mostly involving plugins, specifically the
+Wordpress one. You **don't** need any plugin to benefit from LiteSpeed cache!
+As long as you follow the HTTP specification regarding the caching headers, you can use it as
+a general reverse proxy just like NGINX or Varnish.
+
+LiteSpeed comes in two different variants:
+
+* OpenLiteSpeed (OLS) - the open source product with less features
+* LiteSpeed Web Server (LSWS) - the enterprise version with more features and professional support
+
+The caching module implementations are different and thus have to be configured differently.
+Currently, OLS does support cache tagging and cache tag invalidation and LSWS does not. However, LSWS supports ESI
+whereas OLS does not.
+
+So before you start configuring the server, make sure you know which version of LiteSpeed you are using.
+
+.. note::
+
+    Any LiteSpeed setup works in a single node web server environment only. If you are targeting a multi
+    node setup you might want to consider switching to :ref:`Varnish <varnish configuration>` which has excellent
+    support for this already built-in in this library.
+
+
+Configuring OpenLiteSpeed
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. note::
+
+    You need at least OpenLiteSpeed version 1.4.47
+
+OLS does not support different caching settings depending on ``.htaccess`` settings and different paths.
+If you need that, you have to go with LSWS instead.
+Thus, OLS has to be configured as follows on server or vHost level::
+
+    module cache {
+      # This enables the public cache
+      enableCache                      1
+
+      # This disables the private cache
+      enablePrivateCache               0
+
+      # This enables the public cache
+      checkPublicCache                 1
+
+      # This disables the private cache
+      checkPrivateCache                0
+
+      # Also consider the query string in caches
+      qsCache                          1
+
+      # Disable checking for a cached entry if there's a cookie on the request
+      reqCookieCache                   0
+
+      # We ignore request Cache-Control headers
+      ignoreReqCacheCtrl               1
+
+      # Must be disabled, this tells LS to check the Cache-Control/Expire headers on the response
+      ignoreRespCacheCtrl              0
+
+      # We don't cache responses that set a cookie
+      respCookieCache                  0
+
+      # Configure the maximum stale age to a sensible value for your application
+      # The maxStaleAge defines a grace period in which LS can use an out of date (stale) response while checking on a new version
+      maxStaleAge                      10
+
+      # Make sure we disable expireInSeconds because it would override our Cache-Control header
+      expireInSeconds                  0
+
+      # If you want to use cache invalidation by cache tags, configure the general PURGE endpoint here.
+      # By default, this library is configured to use "/_fos_litespeed_purge_endpoint". If you'd like to
+      # have a different one, configure it here accordingly and make sure you configure the same URI
+      # in the library itself (see further down this page). Also make sure you don't overlook trailing slashes here!
+      purgeuri                         /_fos_litespeed_purge_endpoint
+
+      # Enable the module
+      ls_enabled                       1
+    }
+
+That's all you need. Of course you might want to adjust certain values to your needs.
+Also refer to the OLS docs if you need more details about the different configuration values.
+
+Configuring LiteSpeed WebServer
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. warning::
+
+    Unfortunately LSWS does currently not support invalidating cache tags.
+
+Configuring FOSHttpCache to work with LiteSpeed
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because LiteSpeed does not support a multi node setup configuring the proxy client is pretty straight forward if
+you serve your application only on one domain::
+
+    use FOS\HttpCache\ProxyClient\HttpDispatcher;
+    use FOS\HttpCache\ProxyClient\LiteSpeed;
+
+    $servers = ['127.0.0.1'];
+    $baseUri = 'example.com';
+    $httpDispatcher = new HttpDispatcher($servers, $baseUri);
+
+    $litespeed = new LiteSpeed($httpDispatcher);
+
+If you need multiple domains, make your ``$baseUri`` an array like so::
+
+    use FOS\HttpCache\ProxyClient\HttpDispatcher;
+    use FOS\HttpCache\ProxyClient\LiteSpeed;
+
+    $servers = ['127.0.0.1'];
+    $baseUris = ['example.com', 'foobar.com'];
+    $httpDispatcher = new HttpDispatcher($servers, $baseUris);
+
+    $litespeed = new LiteSpeed($httpDispatcher);
+
+
+If you configured your LiteSpeed instance to use a different ``purgeuri`` than ``/_fos_litespeed_purge_endpoint`` also
+make sure to pass the configured URI like so::
+
+    use FOS\HttpCache\ProxyClient\HttpDispatcher;
+    use FOS\HttpCache\ProxyClient\LiteSpeed;
+
+    $servers = ['127.0.0.1'];
+    $baseUris = ['example.com', 'foobar.com'];
+    $httpDispatcher = new HttpDispatcher($servers, $baseUris);
+
+    $litespeed = new LiteSpeed($httpDispatcher, ['purge_endpoint' => '/your-uri');
+
+Cache Tagging
+~~~~~~~~~~~~~
+
+If you want to use cache tagging please note that you cannot use the default settings of the ``ResponseTagger`` (which
+by default uses  ``X-Cache-Tags``) but instead you have to configure it to ``X-LiteSpeed-Tag`` like so::
+
+    use FOS\HttpCache\ResponseTagger;
+    use FOS\HttpCache\TagHeaderFormatter;
+
+    $formatter = new CommaSeparatedTagHeaderFormatter('X-LiteSpeed-Tag');
+    $responseTagger = new ResponseTagger(['header_formatter' => $formatter]);
+
+

doc/proxy-clients.rst

@@ -24,6 +24,7 @@ Client        Purge   Refresh Ban     Tagging Clear
 ============= ======= ======= ======= ======= =======
 Varnish       ✓       ✓       ✓       ✓
 NGINX         ✓       ✓
+LiteSpeed     ✓       ✓               ✓       ✓
 Symfony Cache ✓       ✓               ✓ (1)   ✓ (1)
 Noop          ✓       ✓       ✓       ✓
 Multiplexer   ✓       ✓       ✓       ✓
@@ -181,6 +182,21 @@ call `setPurgeLocation()`::
     To use the client, you need to :doc:`configure NGINX <nginx-configuration>`
     accordingly.
 
+LiteSpeed Client
+~~~~~~~~~~~~~~~~~
+
+The LiteSpeed client sends HTTP requests with the ``HttpDispatcher``. Create the
+dispatcher as explained above and pass it to the LiteSpeed client::
+
+    use FOS\HttpCache\ProxyClient\LiteSpeed;
+
+    $litespeed = new LiteSpeed($httpDispatcher);
+
+.. note::
+
+    To use the client, you need to :doc:`configure LiteSpeed <litespeed-configuration>`
+    accordingly.
+
 Symfony Client
 ~~~~~~~~~~~~~~
 

doc/proxy-configuration.rst

@@ -3,7 +3,7 @@
 Proxy Server Configuration
 ==========================
 
-You need to configure the proxy server of your choice (Varnish, NGINX or Symfony
+You need to configure the proxy server of your choice (Varnish, NGINX, LiteSpeed or Symfony
 HttpCache) to work with FOSHttpCache. These guides help you
 for the configuration for the features of this library. You will still need to
 know about the other features of the proxy server to get everything right.
@@ -12,4 +12,5 @@ know about the other features of the proxy server to get everything right.
 
     varnish-configuration
     nginx-configuration
+    litespeed-configuration
     symfony-cache-configuration