The HTML5 AppCache and HTTP Authentication

The following article was originally published on the Encodo blogs and is cross-published here.

The following article outlines a solution to what may end up being a temporary problem. The conditions are very specific: no server-side logic; HTTP authentication; AppCache as it is implemented by the target platforms—Safari Mobile and Google Chrome—in late 2012/early 2013. The solution is not perfect but it’s workable. We’re sharing it here in the hope that it can help someone else or serve as a base for a better solution.

The HTML5 AppCache

The application cache is a relatively new feature that is,

• Supported by all modern browsers
• Uses a manifest file that indicates which files to cache
• Browser checks manifest for changes
• If there are changes, all files are refreshed
• External links work when online
• When offline, the application works with the local cache
• External links to non-cached content are redirected to fallback links

AppCache Limitations

Web applications can use the HTML5 application-cache to store local content, but different browsers apply different restrictions to the amount of space allocated per domain.

• Safari Mobile is limited to 50MB per domain. This means that the restriction will generally apply to all content packages downloaded from the same server/domain
• Google Chrome is limited as well, but the actual limit is a bit of a moving target

Optimizing the HTML5 AppCache for Authenticated Content

In particular, the Safari Mobile browser cannot update the application cache for files for which it must obtain authentication.

• Some requests do not trigger authentication

  • Manifest file
  • Home-screen icons
• A lost connection or timeout can invalidate the authentication token
• Version checks are not reliable

  • Open pages/running apps do not check for status updates
  • Home-screen apps don’t reliably check on startup
  • This can lead to out-of-date or missing content

Checking for and presenting updates to the user

The graphic below illustrates the mechanism by which a content package in a web application can manage content updates and present them to the user.

• When online, the software regularly checks whether an update for the package is available
• The user can determine whether to install an update
• When an update has been found, the software stops checking for updates until the user has applied the latest update
• If the user delays the update, the user interface displays an “update” button
• The software will automatically start checking for updates whenever it detects that it is online
• There is no way for a user to ignore updates
• When the user proceeds with an update, the latest version is retrieved at that time, ensuring that the user has the latest version

Activity Diagram for Software Update Cycle

Solving the problems with authenticated data and the AppCache

In order to address the problems described above, the UA products use a separate version file to check for updates independent of the browser’s application-cache mechanism and to trigger this update only when authentication has been reestablished.

Sequence Diagram for Software Update Cycle

• The cache.version.txt file is publicly available but is very small and includes only a unique version number that is also included in the cache.manifest file (both of which are generated by a deployment script).
• The software compares this version number against the last known good version number. If it differs, it knows that the server has been updated with new content for this package
• Before the software can kick off the HTML5 AppCache update process, it must ensure that the user is authenticated and authorized to retrieve the update package (because most browsers will simply fail silently if this is not the case).
• The software pulls the force.password.txt file from the private zone with an explicit request. The browser will ask the user to authenticate, if necessary. This file is also very small to avoid needlessly downloading a large amount of data simply to force re-authentication.
• Once the user has authenticated, the software lets the automated HTML5 AppCache update take over, retrieving first the cache.manifest file and then updating files as needed. The user is notified that this download is taking place asynchronously.
• The software receives a notification from the browser that the update is complete and can record the version number and then notify the user that the update has been applied and is ready to use.

This approach worked relatively well for us, although we continue to refine it based on feedback and experience.