Edge-Side Includes (ESI)

The core mechanism of ESI is the ability to decompose a web page into discrete, cacheable fragments. An ESI processor on the edge server parses the base template and fetches each referenced fragment, assembling the final HTML response on the fly. This allows a page with a Time-To-Live (TTL) of 24 hours to include a personalized shopping cart with a TTL of 0 seconds.

• esi:include tag fetches content from a defined source URL
• esi:inline tag allows content to be embedded directly within the markup
• Fragments can be recursively nested, enabling complex assembly logic

ESI provides robust fault tolerance through built-in exception handling. If a fragment's origin server is unavailable or times out, the edge server can serve a stale-while-revalidate version or a predefined fallback resource, preventing a single backend failure from breaking the entire page.

• esi:try block defines a primary fragment request
• esi:attempt specifies alternative fallback sources
• esi:except handles the final failure state gracefully
• Default timeout behavior can be configured per fragment

ESI supports basic conditional logic based on HTTP request headers, enabling context-aware assembly without hitting the origin server. An edge server can include different fragments based on a user's device type, geolocation, or authentication state by evaluating variables in the incoming request.

• esi:choose acts as a switch statement
• esi:when tests a condition against a header or variable
• esi:otherwise provides a default branch
• Common use case: serving a mobile header fragment vs. a desktop header fragment based on the User-Agent header

ESI allows dynamic string substitution within fragments using variables derived from HTTP headers or explicitly set by the edge server. This enables personalization at the edge without requiring a unique fragment for every user. A single cached fragment can display a user's name or a session-specific token.

• $(HTTP_HEADER{name}) syntax reads request headers
• $(ESI_VARIABLE{name}) references server-defined variables
• Commonly used to inject CSRF tokens or user greetings into otherwise static, highly cacheable HTML chunks

The primary architectural benefit of ESI is the ability to assign independent cache policies to each fragment. A news article body can be cached for hours, while a "Top Stories" sidebar is cached for minutes, and a user-specific "Continue Reading" bar is never cached. This maximizes cache hit ratios while preserving dynamism.

• Fragment TTLs are controlled by standard HTTP Cache-Control headers from the fragment's origin
• Enables a hole-punching strategy for highly dynamic content within static templates
• Dramatically reduces origin server load by caching the page shell and recomposing only the volatile pieces

ESI integrates with surrogate key (or cache tag) systems for precise cache invalidation. When a piece of content changes in the CMS, a single API call can purge all fragments associated with that content's unique key across the entire CDN, without needing to track every URL where it appears.

• A product description fragment can be tagged with a key like prod-12345
• When the product's price updates, a purge request for prod-12345 instantly invalidates all cached instances
• Eliminates the need for full cache flushes or complex URL-based purging patterns

A unique identifier assigned to a piece of content, used to group and purge related cached objects across a CDN without needing to know their individual URLs. This is the primary mechanism for targeted cache invalidation in ESI architectures.

• Enables purging a product description from every page it appears on with a single API call.
• Replaces URL-based purging, which is impractical for highly dynamic, assembled pages.
• Often implemented via response headers like Surrogate-Key.

The process of purging or updating outdated data from a cache when the source content changes, ensuring users receive the most current version of a resource. In an ESI context, this is granular and fragment-specific.

• A single database update can trigger the invalidation of only the affected ESI fragment.
• Prevents the need to flush entire pages, preserving cache hit ratios.
• Relies on surrogate keys or cache tags for precision targeting.

A server-side or edge-side pattern where a final user interface is assembled by aggregating rendered fragments from multiple, independent microservices or templates. ESI is a specific implementation of this broader architectural concept.

• Each fragment can be owned by a different team and deployed independently.
• The assembly layer stitches fragments together based on a page template.
• Contrasts with client-side composition, where assembly happens in the browser via JavaScript.

A geographically distributed network of proxy servers that caches content close to end-users, drastically reducing latency and origin server load. ESI is a native feature of many enterprise CDNs like Akamai, Fastly, and Varnish.

• Processes ESI tags at edge nodes before delivering the assembled page to the client.
• Reduces the distance data travels, improving Time to First Byte (TTFB).
• Provides the distributed compute power necessary for fragment-level assembly at scale.

A distributed computing paradigm that runs application logic and processes data on servers located at the network edge, near the user. ESI processing is a classic edge compute workload.

• Moves assembly logic from a central origin server to globally distributed points of presence.
• Enables personalization logic to execute close to the user without a round-trip to the origin.
• Platforms like Cloudflare Workers and Fastly Compute@Edge offer programmable environments for custom assembly logic beyond basic ESI.

A technique where a web page's HTML is generated on the server for each request. ESI can be used to optimize SSR performance by caching static fragments while still rendering dynamic parts on the server.

• Reduces the load on the SSR infrastructure by offloading cacheable components to the edge.
• Allows a hybrid model where the page shell is statically generated (SSG) and dynamic widgets are included via ESI.
• Improves Time to First Byte (TTFB) for personalized pages by assembling cached and fresh content in parallel.