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

I've included an implementation of the WARP draft in the current  
Apache Wookie (incubating) snapshot if anyone fancies playing with it.  
Its missing a management UI, but you can drop .wgt files in the Wookie  
deploy folder and it will process the access request policy.

E.g.
	 Adding "weather.wgt" with:
	<access origin="http://www.bbc.co.uk/weather/feeds/rss"/>

	 Outputs:
      [java]  INFO [Thread-13] (WidgetFactory.java:213) - access  
policy granted for Weather to access http://www.bbc.co.uk
      [java] 15:38:44,495  INFO ContextListener:176 - Weather - Widget  
was successfully imported into the system.

S

On 4 Mar 2010, at 17:17, Marcos Caceres wrote:

> For the sake of the disposition of comments, I consider my comments  
> disposed of (in a good way) :)
>
> Kind regards,
> Marcos
>
> On 4/03/10 4:28 PM, Robin Berjon wrote:
>> 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."
>>
>> ?
>
> Good enough.
>
>>>> 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.
>
> Ok.
>
>>>> 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!
>
> Great.
>
>>>> 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!
>
> (Oh-oh-oh-oh-oh-oh-oh-oh-oh-oh-oh-oh)
>
>>>> 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!
>
> Alright, not need to get all post-modernist about the meaning of  
> overlapping circles.
>
>>>> 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!
>