Looking at HTML Streaming Using Instart's Custom Headers and Cookies

Instart's HTML Streaming is one of the performance optimizations we provide to customers for accelerating dynamic HTML content. We have a document here in the Help Center titled What is HTML Streaming? that explains the feature and its applicability. The intention of this document is to provide some detail on the headers and cookies that the service adds for the handling of HTML Streaming requests and responses. These can be helpful for understanding why HTML Streaming might not be behaving as expected.

Use browser developer tools to view the request and response headers. (If you don't know how to do this, see the document titled How to Use Browser Developer Tools to Collect the X-Instart-Request-ID Header.) Before you start, clear your browser's cache and cookies so that no stale objects from the browser cache are served.

We insert an X-Instart-Streaming header into the HTTP response to browser requests. This header provides information about HTML Streaming status. If it's working as expected, you should see this after the initial learning period:

x-instart-streaming: HtmlStreaming:HIT

Let's look at what this header contains under some common scenarios when HIT is not present.

Case 1: HTML Streaming MISS - Streaming Cache Miss

x-instart-streaming:HtmlStreaming:MISS,streaming_cache_miss

The first part of the header value, HtmlStreaming:MISS,streaming_cache_miss, tells us that the HTML Streaming did not stream the <HEAD> of the HTML because there was no available cached version of it.

This is normal in the following cases:

  • if this was a response to the very first request for that path that the Instart service has seen.
  • if the TTL of the object in the streamable cache has expired. When this happens we flush the cache and get a new <HEAD> from the origin, so this results in a cache miss.

Case 2: HTML Streaming MISS - Streaming Cache Not Ready

x-instart-streaming:HtmlStreaming:MISS,streaming_cache_not_ready

In this case the header tells us that the HTML Streaming services haven't built the streamable <HEAD> yet. We have a learning period during which we observe the contents of the <HEAD> sent by the origin across a number of requests. At the end of this period we build the streamable <HEAD> based on the learning algorithm and store it in our service's cache.

The default learning period is set to 6 requests, which means we will request the <HEAD> 6 times to learn it before we cache a streamable <HEAD> and be able to send it to a requesting client.

This default value can be configured to a lower/higher number on request. Please contact support@instartlogic.com to set a different learning period for your HTML.

Case 3: HTML Streaming MISS - User Agent Filter

x-instart-streaming:HtmlStreaming:MISS,user_agent_filter

This header means that service did not send the streamable <HEAD> because the browser as identified by its user agent is not active for this feature.

This happens in most cases when the requests is from an unsupported platform or browser. Also, there are some cases where we would turn off HTML Streaming for a set of user agents based on customer request.

Case 4: HTML Streaming MISS - XHR Request

x-instart-streaming:HtmlStreaming:MISS,xhr_request

We consider it as a special case when the request is a XHR request. Though by default we don't do anything different to XHRs – we treat them as a normal request if the content type is HTML – we are able to differentiate XHRs from normal HTTP requests. If you think that HTML Streaming should not be applied to your application's XHR requests, please contact support@instartlogic.com.

Case 5: HTML Streaming MISS - Reloaded Request

x-instart-streaming:HtmlStreaming:MISS,reloaded_request

This is set when the request is a reloaded request. Instart's Nanovisor triggers a reload request when there is a mismatch between the content sent to downstream and what is fetched from the origin. We also set cookies which can help us to understand why there was a mismatch. The following are the most commonly-seen cookies that are set by a reload request.

Table 1: HTML Streaming reload cookies

Cookie nameDescription
instart_html_streamingThe value of this cookie is set to either true or false; true in case HTML Streaming is working normally, false in case HTML Streaming failed for some reason.
instart_reload_reasonThe value of this cookie holds a numeric value. Please refer to the reload reason list below which has the most commonly-seen cookie values and the corresponding reload reasons. Please contact support@instartlogic.com if you have any questions.
instart_reload_additional_infoAdditional information on why this is a reloaded request. Please contact support@instartlogic.com for more details on this.

Table 2: Common reload reasons

ValueDescription
2<HEAD> content mismatch
3Origin responded with a redirect
5Origin response content wasn't HTML
6Origin response error
7Error while parsing HTML
8HTML header mismatch
10Restricted function usage