Fun times with Appcache

When we started work on our responsive web app for managing your library service, Soprano, we had planned offline support since day one. However  we waited to get the basic product launched before sorting out the offline side, as even two years ago it was known to be a difficult beast. We'd actually abandoned a previously attempted offline version of our catalogue due to complexities of retrofitting appcache onto a nice REST-ful site. So we allocated a majority of my time at the tail end of '13 for the offline-ification.

Offline webapps are... Lets be honest, a great idea marred by a particularly bizarre implementation, poor documentation and more gotchas than I can count.  If you're looking for a solid intro to doing it right, see this great article series from the Financial Times . If you want to learn about some of the gotchas, then most have been nicely documented at AppcacheFacts and A List Apart. Hopefully near-future tech like Service Workers will make the process less of a pain, but they are a while off...

This blog post is mostly a grab bag of stuff I haven't seen documented elsewhere, and may help others beating the technology with a stick until it works.

Let's start with the fun of SSL. Imagine you want to build and test your app locally with a similarly secure connection as it does in the real world. To do this you create a self signed certificate.  Well for the love of all that is good make sure you properly install the SSL cert. Recent versions of Chrome and Firefox refuse to store an appcache from an invalid SSL cert. This includes certs that have expired or aren't trusted, or have mismatched domains, or basically anything that might trigger security warnings. And no , you can't just click that nice Proceed Anyway button on the SSL warning screen, that won't work. In Firefox it will die silently and not give you any debug info as to why the appcache download failed. Chrome and Safari will give you a little more info in dev console. You need to properly install the certificate, on a Mac install it to your keychain for Chrome and Safari anyway, Firefox wants to use its own store hidden away in the  nest of preferences panes.

Next, be careful of putting expires headers on, well, anything. You know how all the articles on cache manifest talk about you should never, ever cache the main manifest file or the whole offline version is permanently cached? Well, turns out you have to be a bit careful with Firefox, as if you add expires headers for right now or just in the past, then well the cache instantly expires and won't run the full initial update/download. But be careful of Chrome and Safari, as they do need expires headers or the manifest may get stuck. Yeah, I swallowed my pride and did some browser sniffing for that. Oh, and make sure none of the files referenced in your manifest have past or very short expiry as Firefox respects that and downloading the manifest can fail because of those files.

If you are using appcache, the best way is to have a separate webpage with the manifest and wrap it in an iframe. The main advantage of this is that it ringfences the cache. Normally, when you just add an appcache directly to a page every (matching) GET request you make via AJAX is added to the cache. Leave a one page app for a while and watch those GETs rack up and fill the cache. This means appcache has a built in DDOS mode, whereby when you expire a manifest every file in it gets re-downloaded right then. Using an iframe means you get more control of what gets cached.

That said, if you want IE10 on Win 7 to work with it, iframes might not be the way to go. That particular combo seems to have more trouble actually detecting going offline. IE11 seems to handle it fine.

One fun thing I haven't seen much mention of is the concept of foreign files in appcache. At one point in development we accidentally ended up with two manifest files in different iframes embedded on the same page (due to a mis-built bit of JS). This causes all kinds of fun as you try and work out which version of a file you have between two appcaches, and which cache is the one being used for the page you are viewing. So if you see a file flagged as foreign in Chrome debug, that's likely what's happening.

A note on dev tooling. Chrome and Safari tell you loads about what's going on with an appcache. What's downloaded, where it failed, and so on. It's dev tools also let you know if something's origin is the cache, not a real request. Plus also the url chrome://appcache-internals/ makes flushing bad or wrong ones easy. You'll need to do this lots, since once you add an appcache every http error will go to the fallback cache page, that's fun when debugging issues outside the front-end...

Firefox gives the most unusable debug tool for app cache,  hidden somewhere off in the depths of a sub-dev tools command line. Seriously, the Firefox tool's appcache validate gives really obtuse errors or just fails. It does allow you to quickly flush an appcache, which can be handy, but that's about all it's good for. I'm seriously hoping this gets improved before this stuff gets superseded by the new shiny service worker caches.

Anyway, enough negative, here's positive things: We have a live system using app cache for offline functionality, which is pretty nifty for a responsive back-office application often used where connectivity is unreliable. Lots of dev headache for a really useful thing to people doing a job on the floor.

Who says enterprise software can't do HTML5?