Re: [widgets] Request for Comments: LCWD of Widget Access Request Policy spec; deadline 13-Jan-2010

On Tue, Dec 8, 2009 at 8:06 PM, Arthur Barstow <art.barstow@nokia.com> wrote:
> On December 8, Last Call Working Draft (#2) of the Widget Access Request
> Policy spec was published:
>
>  http://www.w3.org/TR/2009/WD-widgets-access-20091208/
>
> Widget Access Request Policy
> 2. Definitions
>
> An access request is a request made by an author to the user agent for
> the ability to retrieve one or more network resources. The network
> resources and author requests to access are identified using access
> elements in the widget's configuration document.
>

I gots me confused by the second sentence, maybe change to:

"Requests by an author to access network resources can be identified
by the presence of access
elements in the widget's configuration document."


>
> 3. Conformance
> This specification defines conformance criteria that apply to a single
> product: user agents that implement the interfaces that it contains.

It's confusing to talk about "interfaces" here, though I understand
you are talking about interfaces in general terms. I would prefer if
the spec just said:

"This specification defines conformance criteria that apply to a single
product: user agents."

And a "user agent" be defined as "a software application that
implements this specification and the [WIDGETS] specification and it's
dependencies."

> 4. Policy
>
> A user agent enforces an access request policy. In the default policy,
> a user agent must deny access to network resources external to the
> widget by default, whether this access is requested through APIs (e.g.
> XMLHttpRequest) or through markup (e.g. iframe, script, img).

i think you need to make it really clear that you've just defined the
"default policy" for a WUA. Please make it a sub-section or something.


> The exact rules defining which execution scope applies to network
> resources loaded into a document running in the widget execution scope
> depend on the language that is being used inside the the widget.

Typo: "the the"


> 5. The access Element
> Context in which this element may be used:

P&C uses "Context in which this element is used:". It would be nice if
this one said the same thing :)

> 5.1 Attributes
>
> origin
> An IRI attribute that defines the specifics of the access request that
> is requested.

"that is requested" seems tautological... and makes the sentence read
funny (and not "ha ha" funny.)

> Additionally, the special value of U+002A ASTERISK (*)
> may be used.

may > can.

I would rewrite:

"Additionally, an author can use the special value of U+002A ASTERISK (*):"

> This special value provides a means for an author to
> request from the user agent unrestricted access to network resources.

Break here.

> Only the scheme and authority components can be present in the IRI
> that this attribute contains ([URI], [RFC3987]).

I'm really sorry, I'm having a hard time parsing the above sentence.
At first, I thought it was related to the sentence about "*". Can you
change the order of these sentences above. Also, the "*" value is
pretty important, maybe it deserves it's own sub-section even if it
just contains one short paragraph. i'm sure people will come back
asking for clarification once we go to CR as to how it's supposed to
work.

> subdomains
> A boolean attribute that indicates whether or not the host component
> part of the access request applies to subdomains of domain in the
> origin attribute.

It should be clear that "subdomains" and "domain" here refers to
components of RFC-such-and-such, right?

> The default value when this attribute is absent is
> false, meaning that access to subdomains is not requested.

what does it means when I have:

<access domain="http://foo.bar.woo.com" subdomains="true"/>

Everything before "woo.com" is allowed, right? Maybe could be clear in
the spec for people like me :)

> 5.2 Usage example
>
> This example contains multiple uses of the access element (not
> contained in the same configuration as the last one would make the
> others useless).

The above sentence doesn't tell me anything (that I can understand)
about the example. It be nice if it told me what I was looking at a
bit more. Maybe you need to break this up into multiple examples,
showing when it would be appropriate to use "*".

> They presume that http://www.w3.org/ns/widgets is the
> default namespace defined in their context:

Instead of the fancy sentence above, why don't you just add a <widget
xmlns="..."> around the access elements?

> <access origin="https://example.net"/>
> <access origin="http://example.org" subdomains="true"/>
> <access origin="http://dahut.example.com:4242"/>
> <access origin="*"/>

> 6. Processing access elements in the Configuration Document
>
> A user agent must add the following to the Table of Configuration
> Defaults [WIDGETS].

Say that this needs to happen in Step 3, please.

> This processing takes place as part of Step 7 - Process the
> Configuration Document in [WIDGETS].

Can you please move the above sentence above the table. First thing I
thought when I read the first para of this section was "when! when do
I need to do that?!?!?! when!!!" :)

Whoa, hang on. This whole section is not well introduced. Please add
some text at the start of this section integrating the whole thing.
For example, you could say that the section defines an algorithm that
needs to be integrated into the Steps for processing a widget user
agent. Then, make the addendum to Step 3. Follow that hooking into
Step 7.

> Let access-request list be an empty list of objects that represent the
> author's access requests to network resources.

i think the above should be above the sentence starting "For each..."
below the Note.

> The following sequence of steps relies on terminology that is defined
> in RFC 3987 [RFC3987] and in the URI [URI] specification. The
> particular the terms derived from the URI and IRI specifications
> include: host, port, scheme, ifragment, and iuser info.
>
> For each access element that is a direct child of the widget element:

If you would be so kind, could you please add <p> around the text of
each bullet. It makes the algorithm easier to read.


> Let origin be result of applying the rule for getting a single
> attribute value to the value of the origin attribute.

typo: be result > be the result.

rule for getting a single attribute needs link to P&C.

> If origin is not a valid IRI, if it has components other than scheme
> and iauthority, if it has no host component, or if it has a iuser info
> component, then this element is in error and the user agent must
> ignore it.

Broken links for various components (host, iuser, etc)... but you know
that already.


> If scheme is unsupported by the user agent, then this element is in
> error and the user agent must ignore it.

Just ignore the scheme? or ignore the element? I know you mean
"element", but I got confused for a few seconds.

"must ignore it" > "must ignore this element"

> 7. Rules for Granting Access to a Network Resources

Typo: "Network Resources" or "a Network Resource"?

> When multiple access elements are used, the set of network connections
> that are allowed is the union of all the access requests that were
> granted by the user agent.

An example would be nice here, maybe a little venn diagram diagram
would help too :)


> An access request is granted for a given URI if there exists an item
> inside the access-request list such that:
>
> the URI's scheme component is the same as scheme; and
> if subdomains is false, the URI's host component is the same as host; or
> if subdomains is true, the URI's host component is either the same as
> host, or is a subdomain of host; and
> the URI's port component is the same as port.

This is some tricky-ass algebra. You need some example here.


> A. Design Goals and Requirements

Please add "this section is not normative"

> The design goals and requirements for this specification are addressed
> in the 30 April 2009 Working Draft of the Widgets 1.0 Requirements
> [WIDGETS-REQS] document. This document addresses the following
> requirements:
>
> Default Security Policy
> Security Declarations
> Restrict access to external resources (to be published)
> Additional considerations guiding this specification are maximal
> compatibility with existing web technology (including not breaking
> linking to JS libraries, embedded media, ads, etc.); and not
> restricting the platform in such a way that would make it less
> powerful than the web platform.
>
> B. Acknowledgements
>
> The editor would like to thank (in no particular order): the OMTP
> BONDI effort, Jere Kapyaho, Thomas Roessler, Art Barstow, Mohamed
> Zergaoui, Arve Bersvendsen, Stephen Jolly, Marcin Hanclik, Josh Soref,
> and Batman Càceres.

I detect some bias in the ordering of this Acknowledgements :)



-- 
Marcos Caceres
http://datadriven.com.au

Received on Monday, 21 December 2009 15:07:29 UTC