This is an old revision of the document!


This page assumes a general knowledge of LSCache Web Development and ESI use cases. Please visit web dev guide and ESI hole punching page to ensure understanding of those topics before going further.

LiteSpeed can parse the standard ESI tags as well as some LiteSpeed-specific(LSS) tags. The LiteSpeed-specific tags may be used in cases where minifying applications or pagespeed modules are not built to parse the standard esi tags. In addition to html tags, LiteSpeed also has LSS attributes to assist the cache lookup/storage.

The available html tags:

<esi:inline> or <esi_inline> (LSS)

The inline block may be used to cache a section of code separately.

Requires an opening and closing tag.

Attributes:

src - The resource url.

cache-tag - Used for cache *storage*.

cache-control - Like a regular cache-control header, the cache-control attribute is used to determine whether to and how to store the content in cache.

<esi:include> or <esi_include> (LSS)

Generates a second request that is loaded after the main page is loaded. The esi:include response headers should include the various cache headers to determine how it is cached.

Does not require a closing tag

Attributes:

src - The resource url.

cache-tag - Used for private-shared cache *look ups*. Generally should be unique.

cache-control - Used for cache *look ups*. May specify 'no-vary' and 'public' or 'private'

as-var - Setting this value will store the html output during parsing. This is useful for if the esi block needs to be included later in the main file. Using this attribute will reuse the html rather than going back to the backend.

test - Test against a condition before doing the esi include. If the condition is met, parse the esi request. Else do not output. combined - 'parent', 'sub'. A combined esi include will parse the rest of the main request for any other esi includes with the combined=sub attribute. After parsing, a post request is sent to the backend. The post body will include the list of esi includes to parse, so everything is returned in a single response. The post should have the cache control values no-cache and esi=on. Each individual esi include block should be wrapped with an esi inline.

<esi:remove> or <esi_remove> (LSS)

Cannot have a nested ESI tag within.

Used as a backup in case there is no ESI processor. Placed after another ESI tag (e.g. esi:include), if there is an esi processor, anything inside the esi:remove tag is ignored. Else the esi tags will be ignored, so anything inside this tag will be processed normally.

<esi:choose> | <esi:when> | <esi:otherwise> or <esi_choose> | <esi_when> | <esi_otherwise> (LSS)

Works like an esi if/else if/else statement.

Must have an opening and closing tag.

Usable variables and expressions are listed here:

https://www.w3.org/TR/esi-lang

<esi:try> | <esi:attempt> | <esi:except> or <esi_try> | <esi_attempt> | <esi_except> (LSS)

Works like an esi try/catch

Only esi:attempt and esi:except tags are allowed immediately inside esi:try.

<esi:comment> or <esi_comment> (LSS)

This tag may be used to comment esi logic. Could be useful if a developer wishes to leave a comment in an html page without it showing up in the processed html.

<esi:vars> or <esi_vars> (LSS)

Enables the usage of esi vars (listed in the link above in choose/when/otherwise)

In addition to the esi tags, the X-LiteSpeed-Cache-Control response header needs to include 'esi=on'or this can also be done by using rewrite rule to enable ESI.

This notifies the server to parse the response for ESI tags. Upon finding an esi tag, the server will use the attributes to search for a cache entry and if not found, make the esi request. If the 'no-vary' cache control attribute is set, the varies will not be used to locate/store in the cache.

The ESI resource needs to set response headers in order to be cached correctly.

X-LiteSpeed-Cache-Control needs to be set like a normal cache entry (public/private/shared/no-cache, max-age)

Multiple levels of ESI includes is permitted. The maximum number of levels is 10.

ESI is enabled with a simple rewrite rule:-

RewriteRule .? - [E=esi_on:1]

The above rewrite rule in your server-level configurations would activate ESI support for all pages. If you only have ESI on a specific page, you might want to only enable ESI for that page:

RewriteRule /?my_esi_page.php - [E=esi_on:1]

You have page with 3 lines of content , line 1 and line 3 are cache friendly but line 2 is not cache friendly.

<?php
echo 'line 1 - cache friendly';
echo "line 2 - cache unfriendly, generate a random number: " . rand(1,999);
echo 'line 3 - cache friendly';
?>

With ESI we can make this page cached while leave content line 2 still uncached.

add following code into .htaccess to enable ESI

<IfModule LiteSpeed>
RewriteEngine on
CacheLookup on
RewriteRule PAGE_URI - [E=esi_on:1]
RewriteRule PAGE_URI - [E=cache-control:max-age=120]
</IfModule>

max-age=120 means cache it for 120 seconds.

Create main PHP file:

<?php
echo 'line 1 - cache friendly';
echo '<esi:include src="/second.php" cache-control="no-cache"/>';
echo 'line 3 - cache friendly';
?>

Create second PHP file which contents the code that is not cache friendly.

<?php
echo "line 2 - cache unfriendly, generate a random number: " . rand(1,999);
?>

When you access this page, you will see header x-litespeed-cache: hit but each refresh you will see a new randomly number as that part is not cached.

you can also do this by using PHP to send the cache header.

create .htaccess with code:

<IfModule LiteSpeed>
RewriteEngine on
CacheLookup on
</IfModule>

and main PHP file:

<?php
header('X-LiteSpeed-Cache-Control: public, max-age=120, esi=on');
echo 'line 1 - cache friendly';
echo '<esi:include src="/second.php" cache-control="no-cache"/>';
echo 'line 3 - cache friendly';
?>

The only difference for above 2 examples are either using .htaccess to enable ESI or use HTTP header to enable ESI.

  • Admin
  • Last modified: 2019/01/24 11:19
  • by qtwrk