Differences

This shows you the differences between two versions of the page.

--- litespeed_wiki:cache:no-plugin-advanced:esi-support [2019/01/24 11:18]
qtwrk
+++ litespeed_wiki:cache:no-plugin-advanced:esi-support [2019/02/04 10:28]
qtwrk [Response Headers]
@@ Line 1: / Line 1: @@
 ===== LSCache ESI Support =====
+It is assumed that you have a general knowledge of LSCache Web Development and ESI use cases. Please visit [[litespeed_wiki:cache:developer_guide|our Developer Guide]] and [[https://blog.litespeedtech.com/2014/02/19/lsws-5-0-lscaches-esi-support-will-speed-up-web-applications/|our blog post introducing ESI]] to ensure a basic understanding of these topics before proceeding.
-This page assumes a general knowledge of LSCache Web Development and ESI use cases. Please visit [[https://www.litespeedtech.com/support/wiki/doku.php/litespeed_wiki:cache:developer_guide|web dev guide]] and [[https://blog.litespeedtech.com/2014/02/19/lsws-5-0-lscaches-esi-support-will-speed-up-web-applications/|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 cache lookup and storage.
-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.
+=====Available HTML Tags=====
-The available html tags:
+====<esi:inline> or <esi_inline> (LSS)====
-**<esi:inline> or <esi_inline> (LSS)**
+The ''inline'' block may be used to cache a section of code separately.  It requires an opening and closing tag.
-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 to classify content for cache storage.
+  * ''cache-control'' - Used to determine whether content should be cached and how to store it, as with a traditional ''cache-control'' header.
-**src** - The resource url.
+====<esi:include> or <esi_include> (LSS)====
-**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
+This tag generates a second request that is loaded after the main page is loaded. The ''esi:include'' response headers should contain the various cache headers that are needed to determine how the content is to be cached. It does not require a closing tag.
 Attributes:
+  * ''src'' - The resource url.
+  * ''cache-tag'' - Used for private shared cache lookups. Generally, it should be unique.
+  * ''cache-control'' - Used for cache lookups. May specify ''no-vary'' and either ''public'' or ''private''.
+  * ''as-var'' - Setting this value will store the HTML output during parsing. This is useful if the ESI block needs to be included again later in the main file. Using this attribute will reuse the HTML rather than going back to the backend to regenerate it.
+  * ''test'' - Test against a condition before doing the ESI include. If the condition is met, parse the ESI request. Else do not output.
+  * ''combined'' - Value is either ''parent'' or ''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.
-**src** - The resource url.
+====<esi:remove> or <esi_remove> (LSS)====
-**cache-tag** - Used for private-shared cache *look ups*. Generally should be unique.
+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.
-**cache-control** - Used for cache *look ups*. May specify 'no-vary' and 'public' or 'private'
+====<esi:choose> | <esi:when> | <esi:otherwise> or <esi_choose> | <esi_when> | <esi_otherwise> (LSS)====
-**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.
+Works like an ESI ''if''/''else if''/''else'' statement. It must have an opening and closing tag.
-**test** - Test against a condition before doing the esi include. If the condition is met, parse the esi request. Else do not output.
+A list of usable variables and expressions are listed [[https://www.w3.org/TR/esi-lang|at w3.org]].
-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:try> | <esi:attempt> | <esi:except> or <esi_try> | <esi_attempt> | <esi_except> (LSS)====
-**<esi:remove> or <esi_remove> (LSS)**
+Works like an ESI ''try''/''catch''. Only ''esi:attempt'' and ''esi:except'' tags are allowed immediately inside ''esi:try''.
-Cannot have a nested ESI tag within.
+====<esi:comment> or <esi_comment> (LSS)====
-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.
+This tag may be used to comment ESI logic. It is useful if a developer wishes to leave a comment on an HTML page without it showing up in the processed HTML.
+====<esi:vars> or <esi_vars> (LSS)====
-**<esi:choose> | <esi:when> | <esi:otherwise> or <esi_choose> | <esi_when> | <esi_otherwise> (LSS)**
+Enables the usage of ESI variables (listed [[https://www.w3.org/TR/esi-lang|at w3.org]])
-Works like an esi if/else if/else statement.
+===== Enabling ESI Support =====
-Must have an opening and closing tag.
+The server needs to know when to parse for ESI tags in the response body. There are two ways to enable ESI, via rewrite rules and via response header.
-Usable variables and expressions are listed here:
+Multiple levels of ESI includes are permitted. The maximum number of levels is 10.
-https://www.w3.org/TR/esi-lang
+<code>
+<IfModule LiteSpeed>
+RewriteEngine on
+CacheLookup on
+</IfModule>
+</code>
+The above code in ''.htaccess'' is must-have code in order to activate cache, regardless of which method you use to enable ESI.
-**<esi:try> | <esi:attempt> | <esi:except> or <esi_try> | <esi_attempt> | <esi_except> (LSS)**
+==== Response Headers ====
-Works like an esi try/catch
+Response Headers can be used on a more narrow scope, on a page by page basis. The ''X-LiteSpeed-Cache-Control'' response header needs to include ''esi=on''.
-Only esi:attempt and esi:except tags are allowed immediately inside esi:try.
+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 or 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 (i.e. ''public''/''private''/''shared''/''no-cache, max-age'')
+  <?php
+  header('X-LiteSpeed-Cache-Control: public, max-age=120, esi=on');
+  ...
+  ...
+  ...
+  ?>
-**<esi:comment> or <esi_comment> (LSS)**
+==== Rewrite Rules ====
-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.
+Rewrite rules can be used for broader requirements if many pages need to check for ESI.
+  RewriteRule .? - [E=esi_on:1]
-**<esi:vars> or <esi_vars> (LSS)**
+The above rewrite rule 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:
-Enables the usage of esi vars (listed in the link above in choose/when/otherwise)
+  RewriteRule PAGE_URI - [E=esi_on:1]
-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.
+===== Example =====
-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.
-===== Enabling ESI Support =====
-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]
-===== Exapmle1 =====
-You have page with 3 lines of content , line 1 and line 3 are cache friendly but line 2 is not cache friendly.
+You have page with 3 lines of content. Line 1 and line 3 are cache friendly, but line 2 is not.
 <code><?php
@@ Line 110: / Line 100: @@
 ?></code>
-With ESI we can make this page cached while leave content line 2 still uncached.
+With ESI we can cache this page while punching a hole for line 2 and leaving that content uncached.
-add following code into **.htaccess** to enable ESI
+Add the following code to ''.htaccess'' to enable ESI:
 <code><IfModule LiteSpeed>
@@ Line 121: / Line 111: @@
 </IfModule></code>
-max-age=120 means cache it for 120 seconds.
+Note: ''max-age=120'' indicates that the content should be cached for 120 seconds.
-Create main PHP file:
+Create the main PHP file:
 <code><?php
@@ Line 131: / Line 121: @@
 ?></code>
-Create second PHP file which contents the code that is not cache friendly.
+Create a second PHP file which contains the code that is not cache-friendly:
 <code><?php
@@ Line 137: / Line 127: @@
 ?></code>
-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.
+When you access this page, you will see the ''x-litespeed-cache: hit'' header, but with each refresh, you will see a //new// random number. This is proof that line 2 has not been cached.
-you can also do this by using PHP to send the cache header.
+You can also do this by using PHP to send the cache header.
-create **.htaccess** with code:
+Create ''.htaccess'' with the following code:
 <code><IfModule LiteSpeed>
@@ Line 148: / Line 138: @@
 </IfModule></code>
-and main PHP file:
+Create the main PHP file:
 <code><?php
@@ Line 157: / Line 147: @@
 ?></code>
-The only difference for above 2 examples are either using .htaccess to enable ESI or use HTTP header to enable ESI.