Abstract

This specification defines the app: URL scheme.

The app: URL scheme can be used by packaged applications to obtain resources that are inside a container. These resources can then be used with web platform features that accept URLs.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

This document was published by the System Applications Working Group as a Last Call Working Draft. If you wish to make comments regarding this document, please send them to public-sysapps@w3.org (subscribe, archives). All comments are welcome.

Publication as a Last Call Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This specification is a Last Call Working Draft. All persons are encouraged to review this document and send comments to the public-sysapps mailing list as described above. The deadline for comments is 24 June 2014.

Table of Contents

1. app: URL

An app: URL is a [URL] that can be used by a packaged application to address resources within its container (e.g., a .zip file).

2. Instance identifier

The instance identifier is a string that uniquely identifies an instance of a packaged application.

When the instance identifier is not provided by the developer, a user agent MUST synthesize one. The structure and length of identifier represented by the authority is application specific, but it MUST be suitable to use as a Document's origin. See also privacy and security considerations.

2.1 Privacy Considerations

This section is non-normative.

Using unique identifiers (e.g., a UUID) as an instance identifier can be exploited by an adversary as a digital finger print. This can allow a developer to, for example, restore cookies even if the user has cleared cookies from a user agent. As such, if the user agent relies on unique identifiers as the host component, then it should provide end-users with a means of regenerating the authority component. For instance, A user agent can the regenerate the instance identifier when the user clears the user agent's private data.

3. Fetching a resource from a container

This section is non-normative.

To fetch a resource using the app: URL using a request request:

  1. If request's method is not `GET`, or if origin does not match the instance identifier for this application, return a network error.
  2. Let path be the path of URL.
  3. Let response be a response.
  4. If attempting to access the resource at path results in an error (e.g., not found, the file is corrupt, locked, etc.), return a network error and terminate this algorithm.
  5. If request includes a `Range` header:
    1. If the value of the `Range` header is a valid byte range [HTTP11]:
      1. Set response body to be the data from path at the start and end of `Range`.
      2. Set response status to 206.
  6. Otherwise, set the response body to be the data at path.
  7. Set the response headers:
    1. `Content-Length`, computed as per [HTTP11].
    2. `Content-Type`, the MIME type of the resource at path computed as per [SNIFF].
  8. Return response.

3.1 Security considerations

When fetching data from an app: URL, a user agent needs to make sure that only files that were in the container can be accessed (i.e., those files should be sand-boxed). User agents need to watch out for symbolic links (or similar) inside a container, which can attempt to trick the user agent into accessing files that are on other parts of the file system.

4. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].

There is one class of product that can claim conformance to this specification: a user agent.

A user agent is an implementation of this specification.

A. Use Cases

For developers, this specification attempts to address the following use cases:

  1. Provide a URL scheme that is compatible with the features and security model of [HTML], so that applications that are packaged can make full use of web platform's capabilities. For example, the app: URL scheme should be usable as a document's address so that it can serve as its origin, and it should be compatible with APIs like [XHR].
  2. Provide fetching model that constrains retrieval of files to a specific container.
  3. Provide an addressing scheme that is easy to work with - and that developers are already accustomed to working with. The developer should not be bothered as to whether they are using http:// or app:// - the Web's capabilities and APIs need to just work!
  4. Support the ability to playback audio and video files within a packaged web application, including the ability to seek without needing to load the full resource.

B. Examples

The following example shows [HTML]'s window.location using then app: URL.

Example 1
<!doctype html>
<script>
//Example using HTML's Location object
var loc =  window.location; 
console.log(loc.protocol === "app:"); //true 
console.log(loc.host === "com.foo.bar"); //true 
console.log(loc.href === "app://com.foo.bar/index.html"); //true 
console.log(loc.origin === "app://com.foo.bar"); //true 
console.log(loc.pathname === "/index.html"); //true 
console.log(loc.hash === "#example"); //true 
console.log(loc.port === ""); //true
</script>

This example shows an app: URL being resolved in [HTML].

Example 2
var img = document.createElement("img");

//the following setter triggers HTML's resolve algorithm 
img.src = "example.gif"; 

//and the expected output: 
console.log(img.src === "app://c13c6f30/example.gif") //true

//Append the image to the document
document.body.appendChild(img); 
</script>

This example shows a resource within a packaged application being retrieved over [XHR].

Example 3
function process() {
  // process the resulting data 
}

var xhr = new XMLHttpRequest();
xhr.onload = () => process(this.responseText);
xhr.open( "GET", "playlist.json");
xhr.send();

This example shows how an app: URL can be used in conjunction with a HTTP `Range` header to request a range of bytes from a file inside a package.

Example 4
var url = "sample.mp3"; 
var xhr = new XMLHttpRequest(); 
xhr.open('GET', url, true); 
xhr.responseType = "arraybuffer"; 
xhr.setRequestHeader('Range', 'bytes=100-199'); 
xhr.send(); 
console.log(Uint8Array(xhr.response).byteLength === 100);// true

C. Acknowledgments

The bulk of the text in this specifications was derived from the Widget URI scheme specification. The Systems Application working group acknowledge the hard work of the Web Applications Working Group in laying down the foundations for this specification.

D. References

D.1 Normative references

[HTTP11]
R. Fielding et al. Hypertext Transfer Protocol - HTTP/1.1. June 1999. RFC. URL: http://www.ietf.org/rfc/rfc2616.txt
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[SNIFF]
Gordon P. Hemsley. MIME Sniffing Standard. Living Standard. URL: http://mimesniff.spec.whatwg.org/
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: http://url.spec.whatwg.org/

D.2 Informative references

[HTML]
Ian Hickson. HTML. Living Standard. URL: http://www.whatwg.org/specs/web-apps/current-work/
[XHR]
Anne van Kesteren. XMLHttpRequest. Living Standard . URL: http://xhr.spec.whatwg.org/