W3C

Powerbox

Editor's Draft 23 February 2010

Editors:
Tyler Close (Google)
Mark Seaborn (Google)

Abstract

A Powerbox facilitates the creation of links between customer content and resources hosted at Web sites or created on-the-fly from sensors built into the user's Web browsing device. By using the Powerbox, customer content can request access to a user's private resources, regardless of where those resources reside or how they are created.

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 is for review by the Device APIs Working Group and is subject to change without notice. This document has no formal standing within W3C. Please consult the group's home page and the W3C technical reports index for information about the latest publications by this group.

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.

Table of Contents

1 Introduction

This section is non-normative.

Today's users have a great variety of private resources beyond the files stored on their local computing device. Web sites maintain user collections of photos, email, contact information, documents, videos and other types of content. In addition to static content, these sites also offer interactive resources such as discussion forums and event planning. A great variety of such sites exist and ever more are created. Today's computing devices are also typically equiped with many sensors, such as a camera, microphone, geolocation and even physical orientation of the device. These sensors enable quick creation of new resources. In such a resource rich environment, a particular resource might want to support linking and interaction with other resources without being tightly coupled to where these resources are hosted or how they are produced. To meet this need, we introduce a mechanism that enables:

Using this mechanism, customer content can acquire a link to a resource in a uniform way, independent of where the resource is hosted or how it is created. The resource may be created on-the-fly from local sensors, such as the camera, or hosted at a web site, such as a photo sharing site. Similarly, a resource host or creator can offer its resources in a way that makes them readily accessible from customer content. To maintain privacy and security, this facilitated exchange of links between providers and customers remains under the control and direction of the user.

To support compatibility with legacy user-agents and legacy customer content, we reuse the existing file input control in HTML as the mechanism for declaring interest in a particular type of resource. Without changing the syntax or semantics of this HTML element, we extend its scope to also include resources hosted by web sites or dynamically created from local sensors. To support the decentralized development of an ever evolving set of resource types, we reuse the class and accept attributes of the file input control as the namespace for resource types. Customer content declares interest in a particular type of resource by annotating a file input control with particular MIME media types and/or class names. To enable customer content to initiate interactive selection of provided resources, we define an HTTP request pattern for launching a resource provider's resource selection presentation.

2 Conformance Criteria

This specification is written for resource authors and user-agents.

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

In this specification, the terms MUST and MUST NOT are to be interpreted as described in [RFC2119].

A conformant resource is one that implements all the requirements listed in this specification that are applicable to resources.

A conformant user-agent is one that implements all the requirements listed in this specification that are applicable to user-agents.

3 Model

This section provides an overview of the interaction model and definitions of the various actors and artifacts involved in these interactions.

We aim to facilitate user directed introduction of resources to customer content. Customer content declares interest in a particular type of resource identified by MIME media types and/or HTML class names. A Provider is a resource that responds to an HTTP request asking for a provided resource. A Powerbox is the part of a user-agent that mediates introductions of provided resources to Customers. When a user acts on a Customer request, the Powerbox presents the user with a choice of registered Providers. The Powerbox typically does not interpret any part of a Customer request and so does not perform any filtering of Providers. The Powerbox simply forwards a Customer request to a user selected Provider. A Provider responds to this request with a URL for a provided resource, which the Powerbox forwards to the Customer content. An interactive Provider additionally returns a representation to be presented to the user, but withheld from the Customer content. This presentation typically supports user selection or configuration of the provided resource. A non-interactive Provider requires no user interaction to provide a resource and so only returns a URL for the provided resource.

It is expected that Providers will be coarse grained, acting as a gateway to a great number of resources. For example, a given Provider might provide all user accessible resources at a particular Web site. Once selected for a particular Customer request, a Provider can use the specified type identifiers and user interaction to choose among the Provider's resources. Although there may exist a great number of Providers, it is expected that any particular user will only register a small subset of offered Providers with their Powerbox. Consequently, the list of Providers a Powerbox presents to a user is expected to be relatively short.

4 Provider Registration

Content offers a Provider for registration with a Powerbox by including a link with a rel attribute of value Provider. The link's href attribute specifies the Provider URL.

For example, a page offers a Provider by including a <LINK> such as:

<LINK rel="Provider" href="/myvideos" title="Video Selector">

Alternatively, page content offers a Provider by including a <A> such as:

<a rel="Provider" href="/myvideos">Video Selector</a>

A Web site might announce the availability of a Provider in much the same way it does an RSS feed. A site might link to a Provider from all of its pages or only on pages where it's most relevant. Similarly, a browser might signal an offered Provider in much the same way it signals an offered RSS feed, using a passive indicator instead of prompting the user.

A user-agent MUST provide a presentation of an offered Provider that enables the user to request it be registered, unless it is already registered. URI equivalence, using any of the techniques defined in [RFC3986], can be used to determine if an offered Provider is the same as a registered one.

5 Resource Requisition

Customer content makes a requisition for a resource by including a file select control [HTML4].

For example, a requisition for a video is expressed as:

<input type="file" accept="video/*" class="trailer"
       alt="Video for your profile page">

The following [HTML4] attributes of a requisition control are requisition parameters:

If a Customer has additional data to transfer, it can be sent in a subsequent request to the provided resource. The data in the requisition is only intended to support designation of the provided resource.

6 Resource Provision

When a user activates a requisition control, the Powerbox MUST enable user selection of a registered Provider. If the user selects one, the Powerbox sends the selected Provider a request for a provided resource. This provision request MUST be a uniform request [UMP] to the Provider URL with method POST and entity media type application/x-www-form-urlencoded. For any requisition parameters specified on the requisition control, the entity content MUST include a parameter with the same name and value.

For example, a Powerbox might send a provision request like the following one:

POST /myvideos HTTP/1.1
Host: example.com
Content-Type: application/x-www-form-urlencoded

accept=video%2F*&class=trailer&alt=Video+for+your+profile+page

To provide a resource, a Provider MUST respond to a provision request with a 200-level uniform response [UMP] that specifies a provided resource URL in the Location response header. The Powerbox MUST assign this URL to the corresponding requisition control's value attribute. If the response also includes a response entity, the Powerbox MUST present it.

For example, an interactive Provider might return a provision response like:

HTTP/1.1 201 Created
Access-Control-Allow-Origin: *
Location: https://example.com/video123
Content-Type: text/html

<html>
…

The Powerbox displays the HTML content of the response in a new browser tab.

7 Resource Interaction

A provided resource URL can be obtained from the corresponding requisition control's value attribute. This URL may be used with any API supported by the user-agent.

For example, Customer content may extract a provided resource URL from an <INPUT>'s value attribute and assign it to a <IMG>'s src attribute.

7.1 <FORM> Submission

To retain compatibility with existing content, the behavior of a file input control populated by a provision request is compatible with one populated by selection of a file from the local filesystem. If the file control is part of a <FORM> submission, the Powerbox MUST fetch the content to be included in the submission by making a uniform request [UMP] to the provided resource URL with method GET. If the provided resource URL identifies a collection of resources, a success response to this request MUST be of MIME type multipart/mixed, the same format specified by [HTML4] for submission of multiple files. The filename reported in the <FORM> submission MUST be the last segment of the path component of the provided resource URL, where the terms "path" and "segment" are as defined in [RFC3986].

A uniform request is necessary since the provided resource URL is chosen by a remote site. Consequently, it might not be safe for the <FORM> submission to include content that was fetched using credentials.

8 Resource Definition

This section is non-normative.

This section offers advice to resource authors.

Different types of provided resources differ in their support for: types of entity content, URL construction patterns and HTTP methods. A particular Customer may only be able to interact with a provided resource that conforms to some profile of this range of possible behavior. To support interaction with many Customers, a resource author should create resources that conform to existing profiles, such as those defined in standards and identified by a specific MIME media type. When new or custom behavior is required, a new profile can be defined and identified by a MIME media type or a globally unique class attribute. A MIME media type is best used to coordinate entity content syntax. A custom class attribute is especially useful for coordinating URL construction patterns or additional semantics for entity data. A globally unique class name can be generated by extending the namespace defined by the DNS, such as org.example.MyInterface. When responding to a provision request, a Provider should use these identifiers to assist selection of an appropriate resource. A Provider should ignore unrecognized identifiers.

The Powerbox is a general purpose mechanism for introducing Customer content to new and potentially private resources. New types of resources can be made accessible to Web content by using the Powerbox for discovery and introduction, existing user-agent APIs such as XMLHttpRequest for interaction, existing MIME media types for syntax, and HTTP methods for general semantics. In some cases, new class identifiers may need to be defined to coordinate custom interaction patterns, but otherwise, these techniques should often be sufficient to Web-enable a wide variety of hardware and software artifacts.

When deciding how to represent some computer artifact as a collection of resources, aiming for a finer granularity can often make access control issues more easily solved. For example, in the Examples section of this document, a design for making a computer's video camera accessible to Web content is presented. Rather than representing the camera as a single resource to which Web content may be granted access, the presented design instead represents the camera as a sequence of short-lived video capture events. Instead of getting access to the camera itself, Web content only gets access to one of these capture events. When the capture event ends, so does all of the Web content's permission to the camera. Other kinds of artifacts can similarly be subdivided into fine grained resources that match the granularity of typical user interaction patterns.

Since a provided resource URL may be an alias for another resource URL, clients should keep in mind the Web's URI opacity good practice and so not infer any properties of the referenced resource based on the content of a provided resource URL. In particular, a provided resource URL may redirect to a completely different URL identifying a resource hosted at a different Web site.

Examples

This appendix is non-normative.

This section illustrates use of the Powerbox mechanism in a variety of scenarios.

Video Capture

In this scenario, a Customer receives access to a live video stream from a camera attached to the user's computer. The Provider is built into the user-agent, instead of being hosted on the Web.

The Customer content includes a requisition control like:

<input type="file" accept="video/*" class="org.w3c.Broadcast"
       alt="Video for your profile page">

The user activates this requisition control, prompting the Powerbox to present a choice of registered Providers. The user selects the built-in video capture Provider. This non-interactive Provider turns on the computer's video camera and microphone and activates a video recording status indicator in the user-agent's chrome. The Provider responds to the Powerbox with a newly created provided resource URL that identifies the in-progress video stream. The value of this URL is specific to the particular Provider, but it might look like: chrome://camera/live?s=mhbqcmmva5ja3. By including an unguessable secret in the URL, the Provider ensures that, initially, only the Customer has access to the video stream. The Powerbox assigns this URL to the corresponding requisition control's value attribute.

The Customer, knowing it requested a resource of type org.w3c.Broadcast, sends a request to the provided resource asking it to send it's content to the Customer's server. Using an XMLHttpRequest-like API, the Customer sends the following JSON request to the provided resource:

POST chrome://camera/live?s=mhbqcmmva5ja3 HTTP/1.1
Content-Type: text/plain; charset=UTF-8

[ { "@" : "https://example.org/user123/upload/?s=erigsadaslgwu" } ]

In response to this request, the provided resource sends the following request:

POST /user123/upload/?s=erigsadaslgwu HTTP/1.1
Host: example.org
Content-Type: video/mpeg

…

The Customer's site begins receiving the live video stream from the user-agent.

When done recording, the user selects a "Stop" option from the video indicator in the user-agent's chrome. The user-agent turns off the computer's camera and microphone, thus terminating the live video stream. The video upload ends as it reaches the end of the video stream. Further requests to the video stream URL return 410 responses.

References

[HTML4]
HTML 4.01 Specification, D. Ragget, A. Le Hors, I. Jacobs. W3C, 24 December 1999.
[HTTP]
Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee. IETF, June 1999.
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels, S. Bradner. IETF, March 1997.
[UMP]
Uniform Messaging Policy, Level One, T. Close, M. Miller. W3C, 2010.
[RFC3986]
Uniform Resource Identifier (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, editors. IETF, January 2005.

Acknowledgments

This appendix is non-normative.

The editors thank Adam Barth, Anne van Kesteren, Arthur Barstow, Arve Bersvendsen, Bryan Sullivan, Claes Nilsson, Dirk Pranke, Frederick Hirsch, Kenton Varda, Ian Hickson, Mark Miller, Max Froumentin, Robin Berjon, Thomas Roessler.