Feedback on Web-send Introducer from experimental implementation in Firefox

[Mike Hanson]

Hello, Introducers -

I attempted an implementation of the Web-send Introducer specification in Firefox and documented where I had trouble.  Here are my notes:

I didn't implement Register().

I tied my prototype to the OpenWebApps work (which I'm collaborating with the Chrome Web App Store folks with on, by the way), which meant that I already had a persistent collection of user web services.  I simply added a Providers element to my existing web application manifest.  (more at http://github.com/openwebapps)

The introduce-to-welcome flow was confusing and difficult to implement

There is no place in the specification that lays out the flow of control from a call to introduce(), through to the creation of a window and/or iframe, through to a call to welcome(), with the subsequent message exchange.  A section that explicitly laid out this flow is necessary, I believe.

The role of the welcome() method is ambiguous may interact badly with layout

As currently written, the specification suggests that an introduce() implementor should:

1. Construct a list of providers that satisfy the introduce() call's "wanted" argument

2. Present this list to the user

3. When a provider is selected, instantiate an iframe and/or window for the provider, making certain the introduce.welcome() is present in both cases.

4. Render the window and/or iframe (in practice this means opening the window and attaching the iframe as the last child of the anchor's parent as per section 6.

5. Await a call to welcome() from exactly one of the window or iframe.

6. When the welcome() call comes, construct a MessagePort to the context that called welcome(), then invoke the introduce() calls' "callback" argument, passing the MessagePort as the second argument, and the iframe, if it exists, as the third argument.

I'm not entirely sure if that flow is correct; that was based on reading through the spec many times and following the example code closely.

My biggest problem with the flow as specified is that the iframe is attached to the anchor parent's DOM long before the introduce() callback is invoked.  This means the Customer doesn't get a chance to affect the iframe until it calls welcome(), which could be never, or could wait until after some user interaction has happened.  That seems to defeat the maintain-layout-control intent of the API.

Unclear role of welcome()'s second argument

The language in section 8 says that "the second argument is a callback invoked if messaging is enabled".  What does "enabling messaging" connote in this context?  I'm not sure I see any step in the flow that represents an acceptance or enabling of messaging.

Let me know what you think!

-Mike

[Tyler Close]

Hi Mike,

Thanks for getting started on a Firefox implementation. Having two
independent implementations will be a great milestone.

On Wed, Jan 26, 2011 at 3:38 PM, Mike Hanson <mha...@mozilla.com> wrote:
> Hello, Introducers -
> I attempted an implementation of the Web-send Introducer specification in
> Firefox and documented where I had trouble.  Here are my notes:
> I didn't implement Register().
> I tied my prototype to the OpenWebApps work (which I'm collaborating with
> the Chrome Web App Store folks with on, by the way), which meant that I
> already had a persistent collection of user web services.

Could this implementation grow to support register()?

>  I simply added a
> Providers element to my existing web application manifest.  (more at
> http://github.com/openwebapps)

Could you send some deep links to the Introducer stuff?

> The introduce-to-welcome flow was confusing and difficult to implement
> There is no place in the specification that lays out the flow of control
> from a call to introduce(), through to the creation of a window and/or
> iframe, through to a call to welcome(), with the subsequent message
> exchange.  A section that explicitly laid out this flow is necessary, I
> believe.

I've added a new section at:

http://web-send.org/introducer/index.html#workflow

and expanded a little on the example at:

http://web-send.org/introducer/index.html#file-chooser

Does that do the trick, or is more needed?

> The role of the welcome() method is ambiguous may interact badly with layout
> As currently written, the specification suggests that an introduce()
> implementor should:
> 1. Construct a list of providers that satisfy the introduce() call's
> "wanted" argument
> 2. Present this list to the user
> 3. When a provider is selected, instantiate an iframe and/or window for the
> provider, making certain the introduce.welcome() is present in both cases.

First call to welcome() wins, the other is ignored. If there is no
welcome() invocation, the introduce() callback is never invoked.

> 4. Render the window and/or iframe (in practice this means opening the
> window and attaching the iframe as the last child of the anchor's parent as
> per section 6.
> 5. Await a call to welcome() from exactly one of the window or iframe.
> 6. When the welcome() call comes, construct a MessagePort to the context
> that called welcome(), then invoke the introduce() calls'
> "callback" argument, passing the MessagePort as the second argument, and the
> iframe, if it exists, as the third argument.
> I'm not entirely sure if that flow is correct; that was based on reading
> through the spec many times and following the example code closely.

What you describe is as intended.

> My biggest problem with the flow as specified is that the iframe is attached
> to the anchor parent's DOM long before the introduce() callback is invoked.
>  This means the Customer doesn't get a chance to affect the iframe until it
> calls welcome(), which could be never, or could wait until after some user
> interaction has happened.  That seems to defeat the maintain-layout-control
> intent of the API.

The iframe must initially have zero height and zero width. I've added
text to the Provider Loading section clarifying these constraints:

http://web-send.org/introducer/index.html#load

> Unclear role of welcome()'s second argument

That's the callback where the Provider gets a MessagePort to the
Customer. If you've got things working at all, you must have figured
that out, so perhaps you mean something else.

> The language in section 8 says that "the second argument is a callback
> invoked if messaging is enabled".  What does "enabling messaging" connote in
> this context?  I'm not sure I see any step in the flow that represents an
> acceptance or enabling of messaging.

The Provider Loading section says:

"""
The first argument is a list of each [origin] allowed to register the
Provider. Messaging is only enabled if one of these is the same as the
[origin] of the Registrant of the selected Provider. The second

argument is a callback invoked if messaging is enabled.
"""

So messaging is not enabled if the first argument to welcome() does
not contain the origin of the corresponding Registration. This check
prevents a malicious Registrant from causing the user to inadvertently
send an introduction to another Registrant's Provider.

> Let me know what you think!

It sounds like you mostly understood things, but experienced some
frustration getting there. I've tried to smooth out the rough edges
that you explicitly listed. Thank you for being so detailed and
enabling me to improve things. Please try to find more of the rough
edges while the experience is still fresh in your mind, and let me
know if the changes I made fixed things.

Thanks,
--Tyler

--
"Waterken News: Capability security on the Web"
http://waterken.sourceforge.net/recent.html