PubSub.next Proposals

From OpenSocial

Jump to: navigation, search

Notes from 20100817 weingram: After a conversation with Javier and Jon, I have switched gadgets.PubSub to gadgets.Hub. We are proposing this as the new sub-object, due to the similarity between gadgets.PubSub and the incompatible gadgets.pubsub


Contents

About this wiki page

This wiki page is a working page that contains proposals about how to:

Topics

pubsub on top of rpc

There seems to be consensus that the pubsub feature would sit on top of the RPC feature, just like how the current pubsub feature works in Shindig, where (under the hood) any pubsub calls are transmitted between gadget and manager via the RPC mechanism.

Notes from 20091104 meeting: Discussion about possibility of pubsub being a peer to rpc, both using low-level transports, instead of pubsub sitting on top of RPC. Fargo explained that it was pretty much a standard in the code base to sit on top of RPC and has proven to be a good model. To support a feature, you just have to support the new callbacks required by that feature. We would need a compelling reason to not build on top of RPC.

Sharing RPC code between Shindig and OAHub open source

It looks like we have an opportunity to share a major chunk of code between the Shindig open source project and the OpenAjax Hub open source project in a way that preserves backwards-compatibility with both existing specifications.

The OpenAjax engineers believe there is 90% (or more) overlap in the low-level, frame-to-frame messaging logic between the RPC logic in Shindig and similar logic in OAHub, and that the Gadgets logic is much cleaner, and includes OAuth support (something we want to add to OAHub). Furthermore, the OpenAjax engineers believe that it will be possible to do a surgical replacement the existing OpenAjax code with the RPC logic from Shindig.

However, there is at least one security features (Lowe's two token approach for FIM messaging) that exists in current OAHub code that we would need to add to RPC layer to make this a suitable replacement for the existing OAHub logic. (NOTE: There are a few other security features beyond the Lowe fix in the OAHub code that don't exist in Shindig that would be needed, also, but these other features might be above the RPC layer. Three of these other security features are frame hiding when disconnected, optional ability to use timeouts during gadget loading to prevent certain types of phishing attacks, and onunload detection.)

Ideally, we would like to have a single RPC code base that is shared by Shindig and the OpenAjax Hub project, but we have to get deeper into coding to see if in fact such unification is a good idea.

Notes from 20091104 meeting: Sounds good to everyone. We will have a separate meeting on the two token issue in about two weeks.

Secure rpc

OpenAjax people want to have all cross-gadget RPC calls to have a security manager just like the pubsub engine. Apparently, all RPC calls in Shindig go through the manager. Need to confirm this and see whether new security hooks are needed.

(Needs to be fleshed out more)

Notes from 20091104 meeting: Jon/Howard: this is an Enterprise requirement. Fargo says the spec could mandate that RPC must be secure.

2010.05.12 Javier: Added following section.

Security-related proposals for RPC

  • NIX partner authentication - Add a mini-FIM imp to NIX that allows for partner authentication if a proper relay file is provided.
  • 2 security tokens for IFPC - According to http://seclab.stanford.edu/websec/frames/post-message.pdf, using the fragment identifier for communications is only fully secure if both the parent and child provide their own security token. Have the child provide its own security token in the IFPC case.
    • Issue: IFPC may be going away, so maybe no need to pursue this.
    • Issue: Since children (gadgets) automatically connect on load, how to specify authToken to RPC in child case?
  • security alert callback - Add ability to register a security callback from both gadget and container sides. Callback gets invoked for load-timeouts, frame phishing, forged messages, etc. I originally thought about having this as a param to gadgets.rpc.setupReceiver(), but that would make it more difficult to register the callback in the gadget case (setupReceiver() is automatically called in the gadget case). Instead, I suggest adding a gadgets.rpc.setSecurityCallback() function.
    • Issue: Jon suggested adding a gadgets.rpc.config({ securityCallback: <function>, loadTimeout: <number> }) function. This could also be extended in the future for other RPC options. This seems fine to me for the security callback, but I think of load timeout as a per-gadget option and so should be an optional param to setupReceiver() (see 'load timeout' item).
  • load timeout - Allow user to specify a load timeout when setting up a receiver. Add optional parameter to gadgets.rpc.setupReceiver(). If the time specified elapses without the child connecting to the parent, then the security callback (if specified) is invoked with a load timeout security error.
    • Issue: Should there be a default load timeout? Or do we only handle this if the user specifically passes one in?
  • unload detection - If a valid relay file is supplied, always create an iframe with the relay file inside of the gadget (proper loading of the relay file is necessary before RPC considers the client to be connected). Register an "unload" event in the relay file, which will allow the RPC code to detect if an iframe is being maliciously navigated away (frame phishing). Invoke the security callback with a frame phishing alert.
    • Issue: Since this depends on a valid relay file, there will be no frame phishing detection in the case where a relay file is not supplied.
  • gadgets.rpc.getPartnerOrigin() - Returns the origin of the gadget's parent page.

APIs for removing gadgets/RPC receiver

2010.05.12 Javier: Added this section.

It is necessary to remove a gadget from time to time, particularly if there is a security situation. First, we should add an API in shindig-container.js for removing a gadget. Since this is a container detail, it doesn't really belong in the spec. However, it will need to clean up RPC also, so we should add a gadgets.rpc.removeReceiver() API to do cleanup.

Protocol versioning

In Gadgets, if the <Content> element has type="html" (the default), then the Shindig engine is able to inject its own JavaScript logic into the iframe that contains the given gadget's run-time logic. Question: If type="url", is there any communication via RPC between the container application and the gadget?

With OAHub, it is possible for a gadget/widget to be a self-contained HTML file. Here is an example: [1]. In this case, it is expected that the HTML file manually includes its own copy of the OAHub *.js files. This scenario opens us the possibility that the container application and the gadget might be using different implementations of the Hub. To address this, the OAHub open source implementation includes protocol version information so that the two sides of the communications channel can determine whether they are able to communicate with each other. This version information on the communications protocol is not part of the OAHub formal specification at this time, but there has been discussion about formally documenting the protocol sometime in the future.

Neither iWidgets and OAWidgets support type="url". For OAWidgets, there were no vendors who had plans to use this feature. However, further study is needed to see if it makes sense to add this feature to a future version of the OAWidgets spec.

Notes from 20091104 meeting: Long discussion about protocol versioning. Question about whether versioning is on transport layer or pubsub layer or both, and maybe other layers. Fargo said lots of discussion in OSF, also, and they ended up mandating same code on both sides. They pass URL for script to use. Enterprises won't go for this approach because some won't allow foreign/arbitrary JS to be injected into their iframes. Jon/Howard talked about OA techniques. OAHub passes version info about transport layer as URL param because sometimes widgets bundle their own version of Hub (one-way). OA folks had long discussions about this. The OA conclusion was that it's OK to put an implementation version as the parameter. There are going to be leading implementations and people will follow the leading implementations. Too hard to document complete protocols, particularly OpenSocial which has several transport mechanisms. Consensus: Something that might work in practice is version numbers of protocols used by leading implementations with formal documentation on how one or two protocols actually work, such as postMessage and fragment identifier messaging (80/20 rule).

Notes from 20091104 meeting: type=url. Fargo says in practice it's just a glorified iframe. It's possible to implement RPC but very few do this in practice. Moving away from type=url. Jon talked about ILOG efforts on OA side to implement type=url with OA technologies (Hub and Widgets) and the conclusion was it isn't workable, so OA has dropped type=url.

Anonymous pubsub versus sending gadget IDs

OAHub embraces the notion that pubsub is anonymous and does not automatically include any information about the identification of the publishing gadget with the message. Gadgets does transmit the gadget ID, but Fargo said this isn't a critical feature. Howard Weingram of TIBCO has written up a detailed set of arguments about why anonymous pubsub is better and that any attempt to pass gadget IDs around doesn't really work in practice ([2]). From a security perspective, it is probably not a problem in most scenarios if the gadget ID is passed, but nevertheless it is always best from a security perspective to hide as much run-time information from (potentially malicious) gadgets.

The OpenAjax folks would like to either:

  • Not transmit gadget IDs with pubsub (top preference)
  • Provide a configuation parameter that can turn off the transmission of gadget IDs

Not sure at this point how the above might translate into spec and open source.

Notes from 20091104 meeting: Fargo says there is no mandate in Gadgets that mediator has to send the ID of the original sender. Howard explains that ID information needs to be in payload, not in transport. Transport IDs aren't useful. (He wrote treatise on subject.) Consensus: Don't pass internal gadget IDs with the pubsub messages.

tunnel (relay) iframe problematic to some implementations

OAHub uses a tunnel (relay) iframe for most/all Iframe-based gadgets as part of its security bulletproofing as a mechanism to detect onunload events for the gadget iframes. However, some sites that use OpenSocial (FriendConnect?) are unable to support the extra HTML file that is used for the tunnel. We need to study all of the transports to see if onunload detection is possible without using the tunnel.

(Someone needs to provide additional detail on this issue. Then we need to decide whether there is any actions we want to take. Perhaps one "solution" is that the security features from using a tunnel iframe represent a quality-of-implementation aspect to OpenSocial. Some sites can decide to include this security protection, whereas others can take their chances.)

Notes from 20091104 meeting: Howard explains that for security reasons the notification of unload has to be synchronous. Malicious widget can do something bad in the delay. If lots of things in the queue, unload message may never arrive before unload has already occurred. Can't rely on RPC messaging, which is async on postMessage. Forgo says some transports could pass unload synchronously, but not postMessage. Jon asked why so hard for FriendConnect and others to host a tunnel HTML file. Fargo says these workflows are only viable with 1-line SCRIPT element to copy/paste. He says maybe this is just an Enterprise issue and the Enterprise guys can require the tunnel. Howard suggests that when we do the coding we can isolate the unload security piece and have security checks if not there.

New feature name: pubsub-2?

It looks like there is consensus that pubsub should be an optional feature in the Gadgets system, and that a given Gadget will need to include a <Require> or <Optional> element in order to use the pubsub feature.

One question is what name we should give to the official pubsub feature that (hopefully) will be part of OpenSocial 1.1. Some candidates that have been mentioned to date include "pubsub", "PubSub", "OpenAjax", or "openajax-pubsub".

The proposal from the OpenAjax people is that the feature be called either "pubsub" or "PubSub". Note that the Gadgets spec is inconsistent about uppercase and lowercase in high-recommended feature naming:

  • All lower case: flash, i18n, oauth, rpc, skins, window
  • Initial caps: MiniMessage, TabSet
  • Hybrid: oauth.Popup, skins.Property

Jon Ferraiolo recommends "PubSub" under the assumption that there will be at least one change to the APIs versus what exists today in the current (unapproved) "pubsub" feature, and using camelcase naming emphasizes that the new stuff is at least a little different than the old stuff.

Notes from 20091104 meeting: See notes for next section.

Static-based versus instance-based APIs

OpenSocial's APIs are inconsistent between whether to use static-based APIs or instance-based APIs.

Some APIs are global:

  • gadgets.util.registerOnLoadHandler(init);
  • gadgets.Hub.*
  • gadgets.io.*
  • gadgets.window.adjustHeight(...)
  • gadgets.window.setTitle(...)...)
  • gadgets.views.getSupportedViews()
  • gadgets.TabSet.getHeaderContainer()
  • gadgets.Tab.getNameContainer()
  • gadgets.flash.embedFlash()

Whereas some APIs are instance-based:

  • var prefs = new gadgets.Prefs();
  • var v = new gadgets.views.View("canvas");:
  • var tabs = new gadgets.TabSet(__MODULE_ID__, "Two");
  • var msg = new gadgets.MiniMessage(__MODULE_ID__);

The OpenAjax model is instance-based, which allows OpenAjax to support inline gadgets. A typical JavaScript logic pattern within an OA widget would be to have logic that looks something like this: 

var hubClient = OpenAjax.widget.byId("__WID__").OpenAjax.hub;

At the face-to-face meeting on Sept 29, it sounded like there was agreement to use an instance-based approach.

The proposal is that we define an instance-based pubsub mechanism whose API is modelled after TabSet and MiniMessage, and therefore takes __MODULE_ID__ as a parameter to the constructor: 

var pubsub = new gadgets.Hub(__MODULE_ID__);

Then a given gadget could make calls such as: 

pubsub.subscribe(topic, myCallBackFunction);
pubsub.publish(topic, payload);

Subsequent thoughts

The above proposals seems problematic. What happens if a different part of the gadget code wants to get access to the same "gadget instance"? Ideally, each Gadgets would be instance-based (i.e., have its own JavaScript object), and this object could be retrieved via something like this: 

var gadgetInstance = gadgets.byId(__MODULE_ID__);

at which point you could do the following: 

gadgetInstance.Hub.subscribe(topic, myCallBackFunction);
gadgetInstance.Hub.publish(topic, payload);

Notes from 20100816 Howard: Defer the gadgetInstance stuff. For now, stick with gadgets.Hub.


Notes from 20091104 meeting: Fargo says MiniMessage and TabSet are not widely used and not considered best examples, but nevertheless "PubSub" is fine with him. One of the reasons the OA guys want __MODULE_ID__ is to support inlining, an Enterprise requirement, which implies instance-based. Fargo says Gadgets is moving towards cajoling (Caja) for this need. Fargo says instance-based "PubSub" receiving an optional __MODULE_ID__ is fine for widgets that can be inline'd. Howard asked about version info. Fargo says the "opensocial" feature has version info in the feature name and has proven to work well. Therefore, "PubSub1.0" or something like that.

Proposed syntax for pubsub wiring metadata

We need a way to have a gadget tell the manager mashup application which topics the gadget publishes and to which topics the gadget subscribes. This allows the manager application to provide a UI that allows the user to wire publisher gadgets to subscriber gadgets. (Note: Manual wiring is often necessary because there sometimes are multiple widgets publishing to or subscribing to the same topic, such as "date", where one widget might provide a start date and the other widget an end date, and also because sometimes topic names and/or payload types are too generic for automatic mapping.)

In previous discussion, we talked about using the existing <Param> element (child of <Require> and <Optional>) for the wiring metadata. Assuming this continues to make sense, here is a proposal that goes into the next level of detail. Here is a concrete proposal: 

<Require feature="pubsub-2">
  <Param name="topics">
    <Topic title="string" name="string" description="string" type="string"
           publish="boolean" subscribe="boolean" aboutUrl="string">
    </Topic>
    <!-- etc. for other topics -->
  </Param>
</Require>

For backward compatibility purposes, a gadget is permitted to use the following variant: 

<Require feature="pubsub-2">
  <Param name="topics"><![CDATA[ 
    <Topic title="string" name="string" description="string" type="string"
           publish="boolean" subscribe="boolean" aboutUrl="string">
    </Topic>
    <!-- etc. for other topics -->
  ]]></Param>
</Require>

Containers that support pubsub-2 MUST support both variants. The new variant will be the recommended approach once the schema is changed to support complex parameters in OS 1.1. The CDATA approach will be used by gadgets that want to stress backward compatibility with earlier releases, and is likely to persist for some time. 

 <xs:complexType name="GadgetFeatureType">
    <xs:sequence>
      <xs:element name="Param" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base="xs:string">
              <xs:attribute name="name" type="xs:string" use="required"/>
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="feature" type="xs:string" use="required"/>
  </xs:complexType>

The proposal is to support any element as a child of Param. 

 <xs:complexType name="GadgetFeatureType">
    <xs:sequence>
      <xs:element name="Param" minOccurs="0" maxOccurs="unbounded">
        <xs:complexType>
          <xs:any minOccurs="0"/>
          <xs:attribute name="name" type="xs:string" use="required"/>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="feature" type="xs:string" use="required"/>
  </xs:complexType>

or some such thing. Different features may have different types of parameters, or none. Whether the schema is COMPLETELY open at this point may require discussion.


Attributes

Attribute Type Required? Default Comments
name string Required N/A The dot-delimited topic name, e.g. "com.tibco.foo.bar.baz". This name follows the rules defined in the OpenAjax Widget Metadata specification
type string Optional null (i.e. any type is allowed) Type name for the event's payload data. See Types below
title string Optional The value of the name attribute will be used as the title if no title is specified Title for this type of event that is appropriate for a non-technical reader. Howard 2009.11.09: I have added the title attribute to the proposal. Non-technical users may not understand topic names, which take into account things like name-spacing. Title attribute gives a user-friendly title for non-technical users.
publish boolean Optional false True if this gadget publishes events on this topic
subscribe boolean Optional false True if this gadget subscribes to this topic
description string Optional "" A description for the gadget's publish or subscribe endpoint. E.g.: "When this gadget receives an address.xyz event, it displays mass transit options within 10km of the specified address."
aboutUrl string Optional "" A URL pointing to a resource that provides more extensive descriptive information than can be provided in the description attribute."

Child Elements

None

Variables in Topic@name

2010.01.05 Howard: Added this section

The Topic@name attribute needs to support a syntax that allows the gadget to specify user preferences. The rationale for this requirement is discussed here: PubSub.next_TopicMismatches.

The specific syntax used in Topic@name to specify a user preference value SHOULD conform with the standard syntax defined in the OpenSocial specification. 2010.01.05 Howard: At this time, it is not clear whether this standard syntax will be hangman variables, templates, or both.

GadgetXml.VariableAttributes_Proposals

Types

The type attribute is a name that uniquely identifies the the type of data carried in the event payload.

Howard 2010.01.05: Type names SHOULD be URIs and preferably URLs

In general, this name SHOULD be a URI, and preferably a URL. Howard 2009.11.10: Should add recommendation to register type names with a registry such as the OAA one. One reason to use URIs is that URIs are organization-specific, which helps to prevent different organizations from defining different types with the same name.

The asterisk character (*) can be used to indicate that any datatype is allowed. This is the default value for the types attribute.

The specification defines a limited number of common, predefined data types, as summarized in the following table.

Type Name Comments
string ECMAScipt string
number ECMAScipt number
boolean ECMAScipt boolean
array ECMAScipt array, e.g. [ 1, 1, 2, 3, 5, 8 ]. The element type/s are not specified when the generic "array" type is used.
object * ECMAScipt object, e.g. { foo: "bar", baz: "boo" }. The specifics of the object are not specified when the generic "object" type is used.
null * ECMAScipt null
length * Any CSS length value Howard 2009.11.10: CSS version?
color * Any CSS color value
id ID value - probably not useful for OpenSocial Gadgets, but might as well keep the two specs in sync
class * zero of more CSS class names, separated by spaces
style * a string that could be used as value for a 'style' attribute
url A URL Howard 2009.11.09: Do we want "uri" also?
html A fragment of HTML markup.
countrycode * A string that represents an A3 ISO 3166 country code.
languagecode * A string that represents an ISO 639-2 language code.
email A string that represents an e-mail address.
person A string that holds a person's name.
postalcode A string that represents a postal code.
phone A string that represents a phone number.
date * A string that represents a date. MUST be expressed using the "Date Time String Format" defined in the ECMAScript5 specification using one of the date-only forms. For example: "2009-12-15"
time * A string that represents a time of day. MUST be expressed using the "Date Time String Format" defined in the ECMAScript5 specification using one of the time-only forms. For example: "18:45:00Z" or "10:26:24-05:00"
timestamp * A string that represents a date and time of day. MUST be expressed using the "Date Time String Format" defined in the ECMAScript5 specification. For example: "2009-12-15:18:45.000Z"
duration * A string that represents a duration. MUST have format "PYYYY-DDDThh:mm:ss.fff". For example, "P0400-152T20:45:33.123" means "400 years, 152 days, 20 hours, 45 minutes, 33.123 seconds, while "P0003-000T01:56:22.000" means "3 years, 1 hour, 56 minutes and 22.000 seconds." (Must use this one variant defined in the ISO 8601 standard).
* Asterisk, or missing type attribute, means "any datatype"
... Howard 2009.11.10: Include predefined types specific to OpenSocial?

The JavaScript runtime engine will need to do automatic serialization/deserialization into JSON to transmit the payload across frame boundaries.

Notes from 20091104 meeting: Fargo says <Topic> as proposed above looks fine to him, but says he isn't a pubsub expert. He suggests making that proposal to the OpenSocial spec discussion lists. Han asked about multiple representations of a name within an array: how is this handled. Jon explained that the IDE parts of OpenAjax Metadata have extensive features in this area. Howard/Jon suggest that v1 of Gadgets pubsub should be simple. A few basic types and an extensibility mechanism that use a URI to identify custom types. Discussion about having an industry registry for topics and payloads at OpenAjax - OpenAjax Registry. Jon says he thinks he has a programmer to finally do the work in the coming months.

Background Comments

The above element is modelled after the OpenAjax <topic> element described at:

with the following differences:

  • Uppercase <Topic> to match other tagnames in the Gadgets spec
  • For simplicity, the 'datatype' attribute has been shorted to 'type', and only a small subset of the OpenAjax datatypes will be suppored
  • For simplicity, a 'description' attribute instead of a <description> child element
  • No child elements (whereas OpenAjax Metadata allows a number of descriptive-oriented elements on all elements)

Default HubClient

2009.11.17 Howard: Added this section

I am adding the following to our proposal. I have implemented a feature that does this and successfully used it with Apache Shindig.

The PubSub feature performs the following initialization for a gadget.

  1. Set default values.
  2. Register an onLoad handler via gadgets.util.registeronloadhandler
  3. The onLoad handler constructs the HubClient and calls HubClient.connect.

The behavior described in this section ensures that simple gadgets do not need to do anything at all to set up their HubClient instances; but it allows gadgets with special needs to override the default parameters and behavior as required.

Step 1

Step 1 sets default values for the properties used in steps 2 and 3. 

// Create a HubSettings object
gadgets.HubSettings = {};

// Set default HubClient constructor params object
gadgets.HubSettings.params = {
  HubClient: {
    onSecurityAlert: function( alertSource, alertType ) {
      alert( "Gadget stopped attempted security breach: " + alertType );
      window.location.href = "about:blank"; // Forces container to see Frame Phish alert and probably close this gadget 
    }, 
    scope: gadgets
  },
  IframeHubClient: {}
};

// Set default onComplete function for HubClient.connect
gadgets.HubSettings.onConnected = function( hub, suc, err ) { };

2010.05.13 Javier: Changed 'params' object above to have 'HubClient' and 'IframeHubClient' properties, since 'params' is passed directly to IframeHubClient.

Step 2

Step 2 registers an onLoad handler to actually create the HubClient and connect it to the ManagedHub.

Delaying the HubClient creation and connection allows the gadget to override default values stored in gadgets.HubSettings. For example, IframeHubClient supports params properties such as seed, tokenLength and log, which we're not setting by default; and a gadget might need to override onSecurityAlert and/or scope, for which default values are provided. More importantly, perhaps, the onComplete function for HubClient.connect usually sets up the gadget's subscriptions by calling gadgets.Hub.subscribe, or if the connection fails asynchronously, the onComplete function handles the error. 

// Register an onLoad handler
gadgets.util.registerOnLoadHandler( function() {

  try {

    // Create the HubClient.
    gadgets.Hub = new OpenAjax.hub.IframeHubClient(  gadgets.HubSettings.params );

    // Connect to the ManagedHub
    gadgets.Hub.connect( gadgets.HubSettings.onConnect ); 

  } catch(e) {
    // TODO: error handling should be consistent with other OS gadget initialization error handling
  }

} );

Step 3

The gadget loads and the onLoad handler is called. When the gadget succeeds in connecting to the Hub (or when connect fails), the onConnected function is called and the gadget responds appropriately.

Public Spec

The specification must describe this three-step process. Compliant implementations will support it.

The specification must define gadgets.HubSettings. Compliant implementations will allow the gadget to modify the properties of gadgets.HubSettings.

Other Types of HubClients

The sample onLoad handler shown above assumes that the gadget is loaded in an iframe. If we support InlineHubClient and/or CajaHubClient, then the onLoad handler logic will need to detect the gadget's container type and instantiate the appropriate type of HubClient object.

Require Secure Connection

2009.12.06 Howard: Updated proposal

Some gadgets require a higher degree of security than others. Gadgets that require a high-security container must be able to specify this. High-security gadgets need a tunnel window, and thus cannot be instantiated in arbitrary web pages (such as blog pages) where a tunnel is not available.

It is important for a gadget to be able to advertise in the gadget spec (XML metadata) that it requires a tunnel window.

I am proposing that we specify a derivative feature named "gadget-sandbox", e.g.: 

<Requires feature="gadget-sandbox"/>

This feature indicates that the gadget must be securely "sandboxed" in a separate origin AND that a tunnel URL is required. Thus, the gadget-sandbox feature requires ALL of the following:

  • A tunnel URL is provided AND
  • The locked-domain feature is enabled AND
  • The PubSub feature is supported.

The dependency on the PubSub feature exists because you can only have a secure PubSub connection if you have PubSub to begin with.

The dependency on locked-domain exists because isolation of the gadget requires locked-domain.

Possible Options

We might also specify that for a container to support PubSub-secure-connection in the iframe case, it MUST support overriding the seed and token length (see IframeHubClient API in OAH specification). My guess is that nearly all implementers will use default Hub implementations that already do so, so maybe this is not important.

Rejected Alternatives

I considered another approach, which would have added a secureConnection attribute to the PubSub gadget feature. I rejected this approach because it would have involved duplicating existing feature-management functionality (dealing with Requires vs. Optional) in a different way, which would be wasteful.

Additional parameters on subscribe() method

The parameter list for the current gadgets.Hub.subscribe() is a proper subset of the parameter list for OpenAjax's hubClient.subscribe() method. Here is a quick summary of the OpenAjax subscribe() method: 

subscribe(topic, onDataCallback [, scope [, onCompleteCallback [, subscriberData]]])

(The formal spec for this method is at: [3])

Only the first two parameters, topic and onData, are required. Here is a quick description of the parameters:

  • topic - topic name (See [4] for rules on topic names)
  • onData - callback function that should be invoked when someone publishes on the given topic
  • scope - (optional) the "this" object for the callback function
  • onComplete - (optional) callback function that is called when the subscription request has been completed.
  • subscriberData - (optional) the subscription can specify data that should be passed into the onData callback function

Notes from 20091104 meeting: Fargo says 3rd, 4th, 5th params are fine with him, propose to the spec mailing lists. Nice that the APIs are backwards compatible with existing pubsub APIs, but that's not a requirements.

Multiple subscriptions on a given topic

OpenAjax Hub allows a given gadget to make multiple subscriptions on the same topic. One scenario where this is useful is in complex gadget scenarios where a gadget has several independently-developed modules, all designed around an MVC architecture, where different modules want to be subscribe to the same topic. We talked about this feature at a previous face-to-face meeting and we didn't notice any objections to this flexibility at that time.

The "cost" of such flexibility is that each subscription gets its own unique handle, which is delivered to the gadget via a callback function.

(example?)

Notes from 20091104 meeting: Fargo says OK with him. He trusts we are the experts and that his feature has value.

Convenience APIs like OAHub

OAHub has a number of getter APIs that the OpenAjax people feel are necessary in some pubsub scenarios. The OpenAjax engineers haven't had time to develop a complete list, but to get a sense of the convenience APIs that might be proposed, go to [5], and search through the table of contents for the word "get". You'll see APIs such as getScope(), getSubscriberData(), getSubscriberScope(), getParameters(), etc.

The OpenAjax engineers have had some discussion about these APIs are generally feel that:

  • Most (or maybe all) of these APIs should be included in the Gadgets pubsub spec
  • It's probably best to package the APIs as separate getter methods as is done in the OAHub spec because that will likely result in smallest footprint

If we use the bootstrapping approach of: 

var pubsub = new Hub(__MODULE_ID__);

then we might need a new getter function to allow other logic to retrieve the same client instance object. (We need to think this through.)

Detailed proposals need to be developed in this area.

Notes from 20091104 meeting: Howard/Jon say we talked about this and lots of separate getter APIs seem the best approach. Each turns into 1 line JS function. Fargo says propose it and let the spec people review it.

Manager APIs like OAHub

OAHub defines standard APIs for both gadgets and the manager application, whereas the Gadgets spec only defines standard APIs for gadgets. OAHub's manager APIs can be found at:

At the moment, it is an open issue whether it is necessary for Gadgets to include manager APIs similar to OAHub's manager APIs.

Notes from 20091104 meeting: Will know better about this after digging into implementation.

States and managed properties

Both IBM's legacy iWidgets specification and OpenAjax Widgets include the ability for multiple gadgets to share a common bag of properties. In iWidgets, these are called ItemSet and ManagedItemSets. In OpenAjax Widgets, these are "shared properties", where a widget indicates that one of its properties should be shared via the 'sharedAs' attribute on the <property> element:

The existing Gadgets specification includes a UserPrefs feature, which is a subset of similar features found in iWidgets and OpenAjax Widgets.

The OpenAjax members have yet to have in-depth discussion about what exactly what to propose in this area for the Gadgets specification and which version of the Gadgets spec to target for this feature (1.1? 1.2?).

Notes from 20091104 meeting: Fargo says UserPrefs only used by iGoogle. Fargo says no official statement. Fargo suggests that the OA people propose a corollary proposal about sharing state across gadgets. Howard says he will soon submit a proposal about "cached state" for Hub. It's already part of TIBCO PageBus. Jon/Howard agree that we should see if it makes sense to piggyback appdata.

Richer notifiers

OpenAjax Hub provides a number of notifiers that tell a gadget when various operations have been completed. For example, when a gadget subscribes to a topic, there is an optional "onComplete" callback on the subscribe() method which will tell the gadget when the subscription has been completed.

(need more in this section, or maybe this section is redundant with other sections)

Notes from 20091104 meeting: Fargo says fine with him.

Shindig Metadata Servlet Addition

2010.01.25 Howard: I have added this section. The Shindig metadata servlet implementation needs to be updated so that it provides information about feature parameters. Specifically, JsonRpcHandler.java must be updated. I have added the following code at line 162: 

        // Feature details
        // The following renders an object containing feature details, of the form 
        //   { <featureName>*: { "required": <boolean>, "parameters": { <paramName>*: <string> } } }
        JSONObject featureDetailList = new JSONObject();
        for(Feature featureSpec : prefs.getFeatures().values()) {
        	JSONObject featureDetail = new JSONObject();
        	featureDetail.put("required", featureSpec.getRequired());
        	JSONObject featureParameters = new JSONObject();
        	featureDetail.put("parameters", featureParameters);
        	Multimap<String, String> featureParams = featureSpec.getParams();
        	featureParameters.putAll( featureParams );
        	featureDetailList.put( featureSpec.getName(), featureDetail );
        }

The code that adds information to gadgetJson is then modified as follows: 

                  .put("features", features)
                  .put("featureDetails", featureDetailList)
                  .put("userPrefs", userPrefs)

Next steps

Notes from 20091104 meeting:

  • No scheduled phone calls on the overall topic. Attempt to collaborate via email and wiki. Adhoc phone call if determined to be necessary
  • In about two weeks, have a special phone call to talk about the NSL two-token issue when using fragment identifiers for transport
  • Start work on formal spec proposals
  • Start work on open source code changes (may not actually start for a number of weeks due to availability issues)
Retrieved from "http://wiki.opensocial.org/index.php?title=PubSub.next_Proposals"
Personal tools