.. Copyright (c) 2012-2020 Varnish Software AS SPDX-License-Identifier: BSD-2-Clause See LICENSE file for full text of license .. _users-guide-esi: Content composition with Edge Side Includes ------------------------------------------- Varnish can create web pages by assembling different pages, called `fragments`, together into one page. These `fragments` can have individual cache policies. If you have a web site with a list showing the five most popular articles on your site, this list can probably be cached as a `fragment` and included in all the other pages. .. XXX:What other pages? benc Used properly this strategy can dramatically increase your hit rate and reduce the load on your servers. In Varnish we've only implemented a small subset of ESI, because most of the rest of the ESI specifications facilities are easier and better done with VCL:: esi:include esi:remove Content substitution based on variables and cookies is not implemented. Varnish will not process ESI instructions in HTML comments. Example: esi:include ~~~~~~~~~~~~~~~~~~~~ Lets see an example how this could be used. This simple cgi script outputs the date:: #!/bin/sh echo 'Content-type: text/html' echo '' date "+%Y-%m-%d %H:%M" Now, lets have an HTML file that has an ESI include statement:: The time is: at this very moment. For ESI to work you need to activate ESI processing in VCL, like this:: sub vcl_backend_response { if (bereq.url == "/test.html") { set beresp.do_esi = true; // Do ESI processing set beresp.ttl = 24 h; // Sets the TTL on the HTML above } elseif (bereq.url == "/cgi-bin/date.cgi") { set beresp.ttl = 1m; // Sets a one minute TTL on // the included object } } Note that ``set beresp.do_esi = true;`` is not required, and should be avoided, for the included fragments, unless they also contains ```` instructions. Example: esi:remove and ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The `` and `` constructs can be used to present appropriate content whether or not ESI is available, for example you can include content when ESI is available or link to it when it is not. ESI processors will remove the start ("") when the page is processed, while still processing the contents. If the page is not processed, it will remain intact, becoming a HTML/XML comment tag. ESI processors will remove `` tags and all content contained in them, allowing you to only render the content when the page is not being ESI-processed. For example:: The license What happens when it fails ? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ By default, the fragments must have ``resp.status`` 200 or 204 or their delivery will be considered failed. Likewise, if the fragment is a streaming fetch, and that fetch fails, the fragment delivery is considered failed. If you include synthetic fragments, that is fragments created in ``vcl_backend_error{}`` or ``vcl_synth{}``, you must set ``(be)resp.status`` to 200 before ``return(deliver);``, for example with a ``return (synth(200))`` or ``return (error(200))`` transition. Failure to properly deliver an ESI fragment has no effect on its parent request delivery by default. The parent request can include the ESI fragment with an ``onerror`` attribute:: This attribute is ignored by default. In fact, Varnish will treat failures to deliver ESI fragments as if there was the attribute ``onerror="continue"``. In the absence of this attribute with this specific value, Varnish should normally abort the delivery of the parent request. We say "abort" rather than "fail", because by the time Varnish starts inserting the fragments, the HTTP response header has long since been sent, and it is no longer possible to change the parent requests's ``resp.status`` to a 5xx, so the only way to signal that something is amiss, is to close the connection in the HTTP/1 case or reset the stream for h2 sessions. However, it is possible to allow individual ``