Offline resources in Firefox

From MDC

Firefox 3 implements much of HTML 5's support for offline caching of web applications' resources. This is done using the application cache -- a collection of resources obtained from a resource manifest provided by the web application.

[edit] The application cache

Because multiple web applications can share resources (and can even share the same manifest URI), each web application maintains its own cache. However, application caches are grouped based on their shared manifest URI, and have a common 'update status. The update status is one of the following:

idle

The application cache is not currently in the process of downloading updates.

checking

The cache is checking itself against the resource manifest to ensure that it's current.

downloading

The cache is being updated with new content based on a changed resource manifest.

[edit] Resources

The cache always includes at least one resource, identified by its URI, from at least one of the following categories:

Implicit entries

These are resources added to the cache because a top-level browsing context visited by the user included a document indicating that the resource was in its cache using its manifest attribute.

The manifest

This is the resource manifest itself, loaded from the URI specified in an implicit entry's html element's manifest attribute. The manifest is downloaded and processed during the application cache update process. Implicit entries must have the same scheme, host, and port as the manifest.

Explicit entries

These are resources listed in the cache's manifest.

Fallback entries

These are resources that were listed in the cache's manifest as fallback entries. Not supported yet in Firefox.

Opportunistically cached entries

These are resources whose URIs matched an opportunistic caching namespace when fetched, and were therefore cached automatically into the application cache. Not supported yet in Firefox.

Dynamic entries

These are resources added programmatically using the add() method.

[edit] The online whitelist

The online whitelist may contain zero or more URIs of resources that the web application will need to access off the server rather than the offline cache. This lets the browser's security model protect the user from potential security breaches by limiting access only to approved resources.

[edit] The cache manifest

Cache manifest files must be served with the text/cache-manifest MIME type, and all resources served using this MIME type must follow the syntax for an application cache manifest, as defined here. Cache manifests are UTF-8 format text files and may, optionally, include a BOM character. Newlines may be represented by line feed (U+000A), carriage return (U+000D), or carriage return and line feed both.

The first line of the cache manifest must consist of the string "CACHE MANIFEST" (with a single U+0020 space between the two words), followed by zero or more space or tab characters. Any other text on the line will be ignored.

The remainder of the cache manifest must be comprised of zero or more of the following lines:

Blank line

You may use blank lines comprised of zero or more space and tab characters.

Comment

Comments consist of zero or more tabs or spaces followed by a single "#" character, followed by zero or more characters of comment text. Comments may only be used on their own lines, and cannot be appended to other lines.

Section header

Section headers specify which section of the cache manifest is being manipulated. There are three possible section headers:

Section header	Description
CACHE:	Switches to the explicit section. This is the default section.
FALLBACK:	Switches to the fallback section. Note: The fallback section is not yet supported by Firefox, and will be ignored.
NETWORK:	Switches to the online whitelist section. Note: The online whitelist section is not yet supported by Firefox, and will be ignored; however, providing an appropriate online whitelist is strongly recommended.

The section header line may include whitespaces, but must include the colon in the section name.

Data for the current section

The format of data lines varies from section to section. In the explicit section, each line is a valid URI or IRI reference to a resource to cache. Whitespace is allowed before and after the URI or IRI on each line.

Cache manifests may switch back and forth from section to section at will (so each section header can be used more than once), and sections are allowed to be empty.

[edit] A sample cache manifest

This is a simple cache manifest for an imaginary web site at foo.com.

CACHE MANIFEST
# v1
# This is a comment.
http://www.foo.com/index.html
http://www.foo.com/header.png
http://www.foo.com/blah/blah

In this example, there is no section header, so all data lines are assumed to be in the explicit section.

The "v1" comment is there for a good reason. Because the cache is only updated when the manifest changes, if you change the resources (for example, updating the header.png image with new content), you need to change the manifest file in order to let the browser know that it needs to refresh the cache. You can do this by any tweak to the manifest, but having a version number is a good way to do it.

To tell Firefox to use offline application caching for a given web site, the site needs to use the manifest attribute on the html element, like this:

<html manifest="http://www.foo.com/cache-manifest">
  ...
</html>

[edit] The update process

1. When Firefox visits a document that includes a manifest attribute, it sends a checking event to the window.applicationCache object, then fetches the manifest file, following the appropriate HTTP caching rules. If the currently-cached copy of the manifest is up-to-date, the noupdate event is sent to the applicationCache, and the update process is complete.
2. If the manifest file hasn't changed since the last update check, again, the noupdate event is sent to the applicationCache, and the update process is complete. Again, this is why if you change the resources, you need to change the manifest file so Firefox knows it needs to re-cache the resources.
3. If the manifest file has changed, all files in the manifest -- as well as those added to the cache by calling applicationCache.add() -- are fetched into a temporary cache, following the appropriate HTTP caching rules. For each file fetched into the cache, a progress event is sent to the applicationCache object. If any errors occur, an error event is sent, and the update halts.
4. Once all the files have been successfully retrieved, they are moved into the real offline cache atomically, and a cached event is sent to the applicationCache object.

[edit] Features not yet implemented in Firefox

Because the draft standard for HTML 5 was still in flux as we approached the feature freeze date for Firefox 3, there are parts of the offline caching capabilities that aren't yet implemented:

1. The WHATWG draft specification indicates that all requests should come from the offline cache, when available, even if the browser is online. Firefox currently only accesses the offline cache when offline. For that reason, the online whitelist is also not supported yet.
2. Firefox doesn't currently maintain separate caches for each web application. Applications should avoid sharing resources between different manifests unless they're not concerned about conflicting versions of the resources. In general, though, applications should maintain per-application copies of each resource.
3. Firefox doesn't yet support opportunistic caching or fallback entries.

[edit] See also

• HTML 5 working draft: Application caches
• nsIDOMOfflineResourceList