esi
esi;
Available inall subroutines.
Flags a request for parsing edge side includes. Parsing occurs after the vcl_deliver
subroutine has finished, so this statement has no effect if executed in vcl_log
.
Fastly only supports the following ESI directives:
- include
- comment
- remove
When specifying the src URL with <esi:include src=... />
, the URL can be either an absolute or relative URL. If you specify an absolute URL, you must prefix it with http://
or https://
.
<esi:include src="https://example.com/index.html" />
ESI requests are made to your Fastly service as new client requests, with a copy of the HTTP header information from the original client request. If a hostname is specified in the ESI src
attribute, the Host
header of the new request will be set to the value of that hostname, otherwise the Host
header of the ESI request will be the same as for the parent request.
In the above example, the ESI parser takes example.com
in the URL as the Host
request header value (i.e., req.http.host
) and creates a new request to your service. Although you can specify any URL in an ESI include, and the hostname does not have to be one of your service's configured domains you can only forward that request to one of your configured backends. In general, it is often better to use relative links for ESI includes to avoid confusion.
In ESI child requests, the req.topurl
variable is set to the value of req.url
from the parent request.
Limitations and constraints
Performance
ESI tags are processed sequentially, not concurrently, because when the parser encounters an ESI include tag, it will make the child request, wait for the HTTP response from the child request to complete, splice that response into the response stream, and then continue parsing the parent response.
Resource limits
- The maximum depth of
esi:include
processing is5
- The maximum total
esi:include
processing fragments is256
Communication and co-ordination
It is not possible for edge logic within a child request to pass data back to the parent, except by embedding the response body of the child request within the parent. However, it is possible to know whether a request is an ESI child request by checking the value of req.topurl
.
ESI tags within CDATA
Parsing ESI tags within CDATA is not enabled by default. You can set esi.allow_inside_cdata
variable to true
if needed.
ESI with origin compression
In order for the ESI parser to detect <esi:...
tags in the response stream, the response cannot be compressed. Compressed responses will obfuscate the ESI tags and they will be delivered unprocessed to the client.
Try it out
esi
is used in the following code examples. Examples apply VCL to real-world use cases and can be deployed as they are, or adapted for your own service. See the full list of code examples for more inspiration.
Click RUN on a sample below to provision a Fastly service, execute the code on Fastly, and see how the function behaves.
Convert timestamps to relative times like '2 hours ago'
Generate relative time datelines at the Edge instead of in JavaScript or at origin. Better caching, faster rendering, fewer reflows.
Assemble content at the edge with Edge-side includes (ESI)
Use Fastly's support for ESI to combine multiple origin-hosted objects into a single response at the edge.