Proxied Content

From OpenSocial

1 Summary
2 Spec Updates
3 Detailed Proposal
4 Resources

Summary

Allows gadget specs to include an href attribute in a Content section to specify a URI where the container should fetch the HTML to render for the section.

For example, the following gadget would fetch index.html from the example.com server and use the contents of that file in the canvas view of the app.

<?xml version="1.0" encoding="UTF-8"?>
<Module>
  <ModulePrefs title="My App">
    <Require feature="opensocial-0.9"/>
  </ModulePrefs>
  <Content view="canvas" href="http://www.example.com/myapp/canvas/index.html">
  </Content>
</Module>

Spec Updates

http://sites.google.com/site/opensocialdraft/Home/gadgets-api-specification

Detailed Proposal

@href attribute on <Content>

When rendering an OpenSocial Gadget, the container MUST determine if the content for the active view is to be proxied. This is done by checking for the presence of a /Content/@href attribute.

If the attribute is present, the container MUST issue an HTTP request to the URI specified by the href attribute following the rules defined in gadgets.io.makeRequest.

Attributes on the Content element map to makeRequest as follows:

authz: gadgets.io.AuthorizationType (values are canonicalized by converting to lower case. Default value is 'none')
oauth_service_name: gadgets.io.RequestParameters.OAUTH_SERVICE_NAME
oauth_token_name: gadgets.io.RequestParameters.OAUTH_TOKEN_NAME
oauth_request_token: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN
oauth_request_token_secret: gadgets.io.RequestParameters.OAUTH_REQUEST_TOKEN_SECRET
sign_owner: gadgets.io.RequestParameters.SIGN_OWNER (default 'true')
sign_viewer: gadgets.io.RequestParameters.SIGN_VIEWER (default 'true')
refresh_interval: gadgets.io.RequestParameters.REFRESH_INTERVAL

Note that these attributes also apply to Preload elements.

The container MUST also add the following parameters to the URI query string:

lang: The language of the user viewing the page as specified in Section 3 i of the [gadget rendering specification]
country: The country of the user viewing the page as specified in Section 3 i of the [gadget rendering specification]

By default, the request is sent to the remote site MUST be sent to the remote site as an HTTP GET. When the Content section includes Data Pipelining elements, the container MUST send the data to the request URI using an HTTP POST. The structure of this data will match the [JSON-RPC] format.

Processing results

If the response to the proxied request returns a successful HTTP status code, the container MUST interpret the resulting response body according to the rules for content declared inline.

If the response to the proxied request returns an unsuccessful HTTP status code, the container SHOULD present a meaningful error message to the end user. Containers SHOULD obtain a suitable error message for display by displaying the content specified for a view named as view-name.error, where view-name matches the name of the view that the proxied request was being processed for. If an exact match can not be found, the special value default.error should be used. If default.error is not present, the container SHOULD display a generic message indicating that a problem occurred.

Caching

Containers SHOULD cache the results of the HTTP request following the recommendations of section 13 of RFC 2616. If a container does support caching of data, it MUST also support overriding HTTP caching by using the value specified for refresh_interval.

Caches SHOULD be keyed using the following:

The URI of the proxied request
The opensocial owner id, if sign_owner is set to true and requests are authenticated
The opensocial viewer id, if sign_viewer is set to true and requests are authenticated
The language and country passed in to the proxied URI.

Containers MAY cache unsuccessful HTTP responses ("negative caching"), but SHOULD NOT cache unsuccessful responses for a period longer than 5 minutes.

Gadget processing changes

Processing content

The container MUST normalize content bodies in a way that preserves semantic meaning in the resulting HTML output. Specifically, containers MUST preserve the structure of the document for the context the gadget will be rendered in as follows:

If the document is a complete HTML document, including opening and closing html tags, the container MUST retain the semantic meaning of document type definition declarations as well as the relative position of elements in the document
- A container MAY choose to move elements from the head of a document and into the body (or vice versa), but the end result MUST behave the same as the original input
Containers MAY modify the document in other ways for optimization and security purposes as long as semantics are preserved

Processing XML

The container MUST resolve all URI attributes and values relative to the location of the gadget spec xml document. This DOES NOT include links inside of the body of the Content element at this point in time.