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

Hi Marcos,

On Dec 21, 2009, at 16:06 , Marcos Caceres wrote:
>> 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."

Sounds just as confused to me. How about:

"Access element in the widget's configuration document express the author's requests to access network resources."

?

>> 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."

Okay.

>> 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.

A subsection seems overkill for a single sentence. I'll split it into its own paragraph and make sure it's a dfn.

>> 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"

Okay.


>> 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 :)

Okay!

>> 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.)

I'll make it "that is made".

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

Okay.

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

It's HAMMERTIME!

>> 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.

I'll split and clarify.

>> 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?

Yup, adding a reference to RFC 1034.

>> 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 :)

Err no, everything below foo.bar.woo.com. Maybe after reading RFC 1034 it'll be clearer?

"""
A domain is a subdomain of another domain if it
is contained within that domain.  This relationship can be tested by
seeing if the subdomain's name ends with the containing domain's name.
For example, A.B.C.D is a subdomain of B.C.D, C.D, D, and " ".
"""

>> 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 "*".

I'll clarify it somewhat (though it seems perfectly clear to me — it's several examples of the element!).

>> 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?

Because that would make a lot of noise for very little value!

>> 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.

Okay.

>> 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!!!" :)

Okay.

> 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.

Okay.

>> 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.

Probably yes.

>> 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.

But that just spreads it over pages!

>> 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.

Ta.

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

It does link!

>> 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.

Hmmm, they're not broken links, they're just <a> without any href.

>> 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"

Ick, that's really pushing the boundaries of readability. But *shrug*.

>> 7. Rules for Granting Access to a Network Resources
> 
> Typo: "Network Resources" or "a Network Resource"?

Ta.

>> 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 :)

There's no way you'll get a diagram for anything out of me, but if you make one and you explain its semantics to me, I'll be happy to add it!

>> 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.

Err, no it's not!

function okAccess (it, req) {
  return it.scheme == req.scheme && 
         it.port == req.port && 
         (it.subdomains ? isSubDomain(req.host, it.host) : it.host == req.host);
}
//...
if (arList.some(function (it) { okAccess(it, req); }) grantAccess();

>> A. Design Goals and Requirements
> 
> Please add "this section is not normative"

Okay.

>> 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 :)

I need to add Dom!

-- 
Robin Berjon - http://berjon.com/

Received on Thursday, 4 March 2010 15:29:13 UTC