HTTP caching

This page is about remote resource caching. For data caching, see data feed caching.

Introduction

HTTP caching is a technique used to improve the performance and efficiency of web applications. It involves storing a copy of a resource (like a web page, image, or data) so that future requests for that resource can be served faster. This reduces the need to fetch the resource from the original server every time, saving bandwidth and reducing load times.

SpinetiX players have a built-in caching mechanism that is designated to avoid excessive network traffic, meaning that whenever a remote resource needs to be displayed, the player first checks if that resource is already in its local cache. For instance, if inside your Elementi project, an image located on a remote web server needs to be displayed every 30 seconds, the player will use a copy of the image stored in its local cache, instead of downloading that image each time, for as long as the image is not changed on the remote server.

Process

First, some details about how a resource is cached:

• actively cached = the resource was added to cache and the caching period has not ended.
• passively cached = the resource was added to cache and the caching period has ended.

The process:

1. The first time a resource (media file, data / feed source, etc.) must be retrieved from a remote web server, the player downloads that resource and, unless instructed otherwise, also adds a copy to its local cache.
   • The caching duration depends on the remote web server configuration, and it is more accurate if the web server is returning the proper HTTP headers. Nevertheless, the active caching duration is determined and set by the player between 10 seconds and two hours (7200s). More details about caching periods can be found in the player.log.
2. For succeeding requests:
   • If the resource is actively cached, then the player serves it from its local cache.
   • If the resource is passively cached, then the player sends an HTTP HEAD request to determine whether the resource has been changed on the server side.
     • If the result is positive, then it sends an HTTP GET request to retrieve the new version of that resource and updates its cache. The resource is actively cached again.
     • If the result is negative or the remote server cannot be contacted, then the player continues to use the resource from its cache. The resource remains passively cached.

Note:

Any resource not used by the player is removed from cache after maximum 24 hours.

Update delay

The most common problem related to caching is the delay in updating the cache on the player after the resource has been updated on the remote web server.

• During this delay, that can last up to two hours, the player displays the version that is stored in its local cache.
• This is due to improper HTTP headers (or the lack of them) returned by the remote web server.
• You can use a browser add-on (such as "Live HTTP Headers") to verify the returned HTTP headers.
  1. Open a remote resource (for instance an image, a video or an XML file) inside your browser several times with and without updating the file on the server.
  2. Note each time the HTTP headers returned by the web server.
  3. Verify if the HTTP headers are properly modified or left unmodified.

It is recommended to ensure that the proper HTTP headers are returned by the remote web server, but if you don't have access to the remote web server configuration, then "force" the player to check the server after a fixed amount of time using the spx:cacheMaxAge attribute (works only on remote files), the GETURL_ALWAYS_CHECK flag or not to use the caching mechanism at all.

HTTP headers

The player is using the following HTTP headers returned by the remote web server: Cache-Control, Last-Modified and ETag.

The player uses the Cache-Control: max-age directive to determine how long to wait before checking if the resource has been modified on the web server.

• If the max-age directive is not found in the response header, the player computes a caching time depending on the Last-Modified directive. If the document has been modified recently, it will be cached for a short period of time, otherwise it will be cached for a longer one.
• If the Last-Modified directive is not present, then the player starts by caching the document for a short period of time and, if the document remains unmodified, then the caching period increases.

Once the caching time has expired, the player sends a HTTP HEAD request to determine on its own whether the content has changed.

• If the server has provided an ETag directive, then the player sends a HEAD request together with the If-None-Match directive. Otherwise, the player sends a HEAD request together with the If-Modified-Since directive, where the modification date is either the Last-Modified date (if it was returned by the server) or the last time the document was downloaded.
• If the server returns 304 Not Modified, the file is considered as still valid, and therefore it will be checked again next time the cache expires. If the server returns 200 OK, the (new) file is downloaded.
• If the ETag returned by the server is misreporting the state of the file, the player will ignore future server directives about that file, and it will switch to checking periodically (every 10 minutes) whether the file has been changed (by downloading it and running an MD5 check).

Notes:

• For effective Bandwidth management, especially when using 3G modems, you should ensure all remote resources are served with an ETag to avoid unnecessary traffic.
• When creating PHP scripts to serve data to the player, make sure that a valid set of headers are sent, and that the script is capable of handling HEAD request with "If-None-Match" directives.
• For IIS, see also Client Cache page.

Example

A web server might provide some content that should expire after 20 minutes – in that case, the server response would be something like this:

HTTP/1.1 200 OK
Date: Thu, 19 Nov 2009 08:43:52 GMT
Cache-Control: max-age=1200
Expires: Thu, 19 Nov 2009 09:03:52 GMT
Vary: Accept-Encoding
Content-Type: text/xml;charset=UTF-8
Age: 0
Connection: close
Server: YTS/1.17.22

The directive "max-age=1200" above makes the cached content expire after 20 minutes. After that period, the player sends a HEAD request to determine whether the content has changed – if it did, it issues a GET request for the content, otherwise it continues playing the content from the cache, up to a maximum time of 24 hours.

Disable caching

The player cache is designed to save bandwidth and it should be used as much as possible. However, there may be some scenarios where you want to deliberately avoid the cache (for example, when timely information might be displayed incorrectly). In order to do this, you need to use one of the following methods:

• For remote media elements (video, image, etc.), use the spx:cacheMaxAge attribute and set its value to 0.
• For remote files retrieved using JavaScript code, you can use a unique query string on the resource URI each time it's invoked, or call jSignage.ajax() with the "cache" parameter set to "false", or the getURL() method without any flags.
• For legacy HMD news templates, see how to set no caching.