Widget URIs

This specification defines the widget URI scheme that is used to address resources inside an packaged/installed Web Application. It is intended to be used with applications running is a packaged container (e.g., a [[ZIP]] container, or a [[!WIDGETS]] package) or similar sand boxed local file system.

Introduction

Widget URIs are synthetic URIs that serve two purposes:

Can be used by a user agent as a document's address [[HTML5]], which can serve as the origin for HTML or SVG applications, which enables the use of many features that rely on the same-origin policy and allows certain DOM attributes to be resolved [[!HTML]].
Provides a means to retrieve data from a file within a package simulating a [[!HTTP]] GET request semantics through [[!HTTP]] response codes. This allowing as to be used, for instance, with [[XMLHTTPRequest]] and for elements to fire appropriate events when files cannot be found in a package.

An example of a widget URIs is:

widget://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html

Example of usage

Assuming the synthesized document's address [HTML] is widget://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html#example.


<!doctype html>
<script>
//Example using HTML's Location object
var loc =  window.location; 
console.log(loc.protocol ===  "widget:"); //true 
console.log(loc.host     ===  "c13c6f30-ce25-11e0-9572-0800200c9a66"); //true 
console.log(loc.href     ===  "widget://c13c6f30-ce25-11e0-9572-0800200c9a66/index.html"); //true 
console.log(loc.origin   ===  "widget://c13c6f30-ce25-11e0-9572-0800200c9a66"); //true 
console.log(loc.pathname === "/index.html"); //true 
console.log(loc.hash     === "#example"); //true 
console.log(loc.port     === ""); //true

This example shows a widget URI being resolved in [[!HTML5]].


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 === "widget://c13c6f30-ce25-11e0-9572-0800200c9a66/example.gif") //true

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

This example shows a resource within a package being retrieved over [[XMLHTTPREQUEST]].


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

function handler() {
 if(this.readyState == 4 && this.status == 200) {
		var text = this.responseText;
		var json = JSON.parse(text) 
		process(json); 	
 } else if (this.readyState == 4 && this.status != 200) {
      // fetched the wrong page or there was an error...
 }
}

var xhr = new XMLHttpRequest();
xhr.onreadystatechange = handler;
xhr.open("GET", "playlist.json");
xhr.send();

Syntax of Widget URIs

A widget URI is an [[!URI]] that:

adheres to the IRI grammar rule from [[!RFC3987]],
its scheme component is the case-insensitive string "widget" ,
contains an authority that meets the requirements of this specification.

A widget URI reference is one that:

adheres to the IRI-reference grammar rule from [[!RFC3987]],
if it is an absolute URI reference then it is a widget URI.

Synthesizing a widget URI

When synthesizing a widget URI, a user agent MUST are normalized the URI in accordance with chapter 5.3.2. "Syntax-Based Normalization" of [[!RFC3987]].

Authority Component

The authority is a unique string which can be heuristically generated upon demand such that the probability that two are alike is small, and which is hard to guess. The authority component is said to be opaque, meaning that the authority component has a syntax as defined by [[!RFC3987]] but that the authority component is devoid of semantics.

We strongly is RECOMMENDED using a [UUID] as the as the value of the authority .

Query Component

The query component, when present, contains data that complements the path component in identifying a resource within a package.

Dereferencing and retrieval

This section describes how a user agent is supposed to respond requests to retrieve resources from a widget URI. The purpose is to make responses "look and feel" as much as possible like regular HTTP requests.

To dereference a widget URI to a file in a widget package a user agent MUST apply the rules for dereferencing a widget URI.

The rules for dereferencing a widget URI are as follows:

If the request is not a GET request, return a 501 Not Implemented response and terminate this algorithm.
If the URI uses the scheme 'widget', but is not a valid widget URI, return a 400 Bad Request response and terminate this algorithm.
If the URI uses the scheme 'widget', but the authority does not match the one assigned to this package, return a 403 Not Allowed response and terminate this algorithm (i.e., prevent inter-widget content access).
If the user agent implements [[!Widgets]] (for the purpose of internationalization):
1. Let potential-file be the result of running the rule for finding a file within a widget package using the path component as its parameter.
Otherwise,
1. Let path be the path to the file being sought by the user agent.
2. Let potential-file be the result of attempting locate the file at path
If potential-file is not found, return a 404 Not Found response.
If retrieving potential-file results in a error (e.g., the file is corrupt), return a 500 Internal Server Error with an optional message describing the error in the response body.
Let content-type be the result of applying the rule for identifying the media type of a file using potential-file as an argument.
Return a 200 OK response, with the value of content-type as the Content-Type header, and with potential-file as the response body.